仓库自包含化：CI/文档/规范入库，升级 echarts，填关于页链接
This commit is contained in:
@@ -0,0 +1,24 @@
|
||||
name: CI
|
||||
|
||||
# 仅分支推送触发:tag 推送交给 release.yml;solo 开发不走 PR,去掉 pull_request 避免同一提交双跑
|
||||
on:
|
||||
push:
|
||||
branches: ["**"]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest-amd64
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "24"
|
||||
cache: npm
|
||||
- name: 安装依赖
|
||||
run: npm ci
|
||||
- name: ESLint(检查模式)
|
||||
run: npx eslint .
|
||||
- name: 类型检查
|
||||
run: npm run typecheck
|
||||
- name: 构建
|
||||
run: npm run build
|
||||
@@ -0,0 +1,34 @@
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ["v*"]
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest-amd64
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "24"
|
||||
cache: npm
|
||||
|
||||
- name: 构建并打包 dist.zip
|
||||
run: |
|
||||
npm ci
|
||||
npm run build
|
||||
cd dist && zip -qr ../dist.zip . && cd ..
|
||||
|
||||
- name: 提取 CHANGELOG 版本段作为 Release 描述
|
||||
run: |
|
||||
TAG="${{ gitea.ref_name }}"
|
||||
awk -v ver="${TAG#v}" '$0 ~ "^## \\[" ver "\\]" {flag=1; next} /^## \[/ && flag {exit} flag {print}' CHANGELOG.md > release-notes.md
|
||||
[ -s release-notes.md ] || echo "Release ${TAG}" > release-notes.md
|
||||
|
||||
- name: 创建 Release 并上传 dist.zip(重跑幂等,同名附件自动替换)
|
||||
uses: https://gitea.com/actions/gitea-release-action@v1
|
||||
with:
|
||||
token: ${{ secrets.BUILD_TOKEN }}
|
||||
body_path: release-notes.md
|
||||
files: dist.zip
|
||||
@@ -0,0 +1,23 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "24"
|
||||
cache: npm
|
||||
- name: 安装依赖
|
||||
run: npm ci
|
||||
- name: ESLint(检查模式)
|
||||
run: npx eslint .
|
||||
- name: 类型检查
|
||||
run: npm run typecheck
|
||||
- name: 构建
|
||||
run: npm run build
|
||||
@@ -0,0 +1,40 @@
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ["v*"]
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "24"
|
||||
cache: npm
|
||||
|
||||
- name: 构建并打包 dist.zip
|
||||
run: |
|
||||
npm ci
|
||||
npm run build
|
||||
cd dist && zip -qr ../dist.zip . && cd ..
|
||||
ls -lh dist.zip
|
||||
|
||||
- name: 提取 CHANGELOG 版本段作为 Release 描述
|
||||
env:
|
||||
TAG: ${{ github.ref_name }}
|
||||
run: |
|
||||
VERSION="${TAG#v}"
|
||||
awk -v ver="$VERSION" '$0 ~ "^## \\[" ver "\\]" {flag=1; next} /^## \[/ && flag {exit} flag {print}' CHANGELOG.md > release-notes.md
|
||||
[ -s release-notes.md ] || echo "Release ${TAG}" > release-notes.md
|
||||
|
||||
- name: 创建 Release 并上传 dist.zip
|
||||
uses: softprops/action-gh-release@v3
|
||||
with:
|
||||
token: ${{ github.token }}
|
||||
body_path: release-notes.md
|
||||
files: dist.zip
|
||||
@@ -0,0 +1 @@
|
||||
0.6.5
|
||||
@@ -0,0 +1,5 @@
|
||||
# API 层与状态管理规范
|
||||
|
||||
- 所有请求经统一 request 封装(`src/api/request`):注入 JWT、401 统一跳登录、错误统一提示;组件内不直接 `fetch`/裸 axios。
|
||||
- 跨页面共享状态才进 Pinia;页面内状态用 `ref`/`computed` 就地管理,不把一切塞 store。
|
||||
- 请求函数返回类型化数据(`Promise<Instance[]>`),错误向上抛由封装层兜底,不在每个调用点重复 try/catch。
|
||||
@@ -0,0 +1,59 @@
|
||||
# Component Guidelines
|
||||
|
||||
> How components are built in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's component conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What component patterns do you use?
|
||||
- How are props defined?
|
||||
- How do you handle composition?
|
||||
- What accessibility standards apply?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Component Structure
|
||||
|
||||
<!-- Standard structure of a component file -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Props Conventions
|
||||
|
||||
<!-- How props should be defined and typed -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Styling Patterns
|
||||
|
||||
<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Accessibility
|
||||
|
||||
<!-- A11y requirements and patterns -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Component-related mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -0,0 +1,36 @@
|
||||
# 前端目录结构
|
||||
|
||||
> Vue 3 前端工程的目录职责与命名约定。
|
||||
|
||||
## 目录职责
|
||||
|
||||
```text
|
||||
oci-portal-dash/
|
||||
├── package.json 脚本 dev / build / typecheck / lint / format
|
||||
├── vite.config.ts @ 别名指向 src/;dev 代理 /api → localhost:8080
|
||||
├── .env.development VITE_MOCK=1,开发默认走内置 mock 数据
|
||||
├── index.html
|
||||
└── src/
|
||||
├── main.ts 应用入口,挂 Pinia 与 router
|
||||
├── App.vue NConfigProvider 注入 Naive 主题
|
||||
├── assets/ main.css:Tailwind @theme 设计 token(浅色)+ html.dark 暗色变量覆盖与全局基础样式
|
||||
├── theme/ tokens.ts(JS 侧 token 唯一来源,含 darkTokens 暗色板)、naive.ts(亮暗两套 themeOverrides 同一工厂生成)
|
||||
├── types/ api.ts:与 docs/API接口文档.md 一一对应的 DTO 类型
|
||||
├── api/ request 封装(JWT 注入、401 跳登录、错误 hint 拼接)+ 按资源分模块;VITE_MOCK=1 时返回 mock.ts 数据
|
||||
├── stores/ Pinia:auth(令牌持久化)、app(侧栏收缩、暗色主题:默认跟随系统 + localStorage 记忆,驱动 html.dark 与 Naive darkTheme)、scope(全局作用域:租户/区域/区间,localStorage 按租户记忆)
|
||||
├── router/ 路由与登录守卫
|
||||
├── composables/ useAsync(异步状态)、useFormat(时间/字节/OCID 格式化)、useRegionAlias(区域友好名)、useTransientPoll(过渡态自动轮询:实例电源 / 挂载操作后每 5 秒刷新至稳态)
|
||||
├── components/ StatusBadge、OcidText、CostChart 等复用组件;表单基座 FormModal / FormField(hint 问号 tooltip + error / feedback 下置提示)/ FormSection(分组标题)/ FilePicker(含 compact 单行态)/ AppInputNumber(数字框统一封装:右侧垂直上下箭头步进);tenant/ 下为租户详情各 tab 与失联占位 DeadPlaceholder(失联时整体替换 tab 内容),storage/ 下为引导卷编辑 / 挂载弹窗,task/ 下含 CronEditor 可视化编辑器与任务表单(tab 分类型),instance/ 下含 InstanceSpecForm(实例规格表单,创建实例弹窗与抢机任务共用),logs/ 下为日志页各 tab 面板(SystemLogPanel 系统日志、LogEventPanel 回传日志)
|
||||
├── layouts/ AppLayout(顶栏 + 内容区,顶栏右侧为全局作用域租户 / 区域选择器)、SidebarNav(分组导航、收缩态)
|
||||
└── views/ 页面:登录、总览、租户列表/详情、实例列表/详情、网络、VCN 详情、引导卷列表(编辑 / 挂载 / 删除以弹窗内联完成,无单独详情页)、任务、日志(tab 结构:「系统日志」操作留痕,预留回传日志)、设置(tab 结构:「通知」通知管理 + Telegram 配置,「任务」抢机熔断阈值)等
|
||||
```
|
||||
|
||||
## 全局作用域约定
|
||||
|
||||
租户 / 区域在顶栏右上角全局选择,区间在各资源列表页内选择,三者经 scope store 全站共享——实例 / 网络 / 引导卷页跟随同一作用域查询单租户数据,切页无需重选;选择按租户记忆在 localStorage,未开启多区域 / 多区间支持的租户对应选择器禁用锁定默认值。租户导入 / 修改 / 删除 / 测活、订阅新区域成功后经 `scope.refreshConfigs()` 即时刷新全局选择器,无需刷新页面。
|
||||
|
||||
## 命名约定
|
||||
|
||||
- `src/` 下按职责分层:`views/`(页面)、`components/`(复用组件)、`composables/`、`api/`(接口封装)、`stores/`(Pinia)、`types/`、`assets/`。
|
||||
- 组件文件 PascalCase(`TaskLogDrawer.vue`),composable/工具文件 camelCase,路由路径 kebab-case。
|
||||
- `api/` 模块按后端资源划分(`instances.ts`、`tasks.ts`…),函数名与接口语义对应,不散调 axios。
|
||||
@@ -0,0 +1,51 @@
|
||||
# Hook Guidelines
|
||||
|
||||
> How hooks are used in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's hook conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What custom hooks do you have?
|
||||
- How do you handle data fetching?
|
||||
- What are the naming conventions?
|
||||
- How do you share stateful logic?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Custom Hook Patterns
|
||||
|
||||
<!-- How to create and structure custom hooks -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Data Fetching
|
||||
|
||||
<!-- How data fetching is handled (React Query, SWR, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
<!-- Hook naming rules (use*, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- Hook-related mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -0,0 +1,44 @@
|
||||
# Frontend Development Guidelines(oci-portal-dash 前端规范)
|
||||
|
||||
> Vue 3 前端(`oci-portal-dash/`)编码规范入口。
|
||||
|
||||
---
|
||||
|
||||
## 技术栈约束
|
||||
|
||||
Vue 3 + Vite + TypeScript + Naive UI + Tailwind CSS v4 + ECharts + Pinia。Naive UI 承担组件视觉(`themeOverrides`),Tailwind 只承载设计 token 与布局工具类。
|
||||
|
||||
---
|
||||
|
||||
## Guidelines Index
|
||||
|
||||
| Guide | 内容 |
|
||||
|-------|------|
|
||||
| [Directory Structure](./directory-structure.md) | src 分层、文件命名与全局作用域约定 |
|
||||
| [TypeScript & Vue](./typescript-vue.md) | TS 严格模式与组件写法 |
|
||||
| [Styling & Design Tokens](./styling-design-tokens.md) | Anthropic 风设计 token、字体与反模式清单 |
|
||||
| [API & State](./api-and-state.md) | 请求封装与 Pinia 使用边界 |
|
||||
|
||||
---
|
||||
|
||||
## Pre-Development Checklist
|
||||
|
||||
写代码前确认:
|
||||
|
||||
- [ ] 读过 [Directory Structure](./directory-structure.md),文件放对层(views / components / composables / api / stores / types)
|
||||
- [ ] 涉及颜色、圆角、间距时先看 [Styling & Design Tokens](./styling-design-tokens.md),禁止硬编码 hex
|
||||
- [ ] 新增请求走 `api/` 统一封装,DTO 类型进 `types/`(与 `docs/API接口文档.md` 一一对应)
|
||||
- [ ] 出 UI 设计稿前读 `../guides/design-workflow.md`
|
||||
|
||||
## Quality Check
|
||||
|
||||
提交前必过:
|
||||
|
||||
```bash
|
||||
npm run lint # ESLint(flat config,含 eslint-plugin-vue recommended)+ Prettier
|
||||
npm run typecheck # vue-tsc --noEmit
|
||||
npm run build # 类型检查 + 产物构建
|
||||
```
|
||||
|
||||
- 提交信息沿用项目规范(中文、≤50 字),不采用 Conventional Commits。
|
||||
- 依赖变更后 `package.json` 与 lockfile 一起提交;不提交 `node_modules`、构建产物。
|
||||
@@ -0,0 +1,51 @@
|
||||
# Quality Guidelines
|
||||
|
||||
> Code quality standards for frontend development.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's quality standards here.
|
||||
|
||||
Questions to answer:
|
||||
- What patterns are forbidden?
|
||||
- What linting rules do you enforce?
|
||||
- What are your testing requirements?
|
||||
- What code review standards apply?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
<!-- Patterns that should never be used and why -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Required Patterns
|
||||
|
||||
<!-- Patterns that must always be used -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
<!-- What level of testing is expected -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
<!-- What reviewers should check -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -0,0 +1,51 @@
|
||||
# State Management
|
||||
|
||||
> How state is managed in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's state management conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What state management solution do you use?
|
||||
- How is local vs global state decided?
|
||||
- How do you handle server state?
|
||||
- What are the patterns for derived state?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## State Categories
|
||||
|
||||
<!-- Local state, global state, server state, URL state -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## When to Use Global State
|
||||
|
||||
<!-- Criteria for promoting state to global -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Server State
|
||||
|
||||
<!-- How server data is cached and synchronized -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
<!-- State management mistakes your team has made -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -0,0 +1,111 @@
|
||||
# 样式与设计 Token 规范
|
||||
|
||||
> Anthropic 风(warm editorial)设计体系:色板、字体、圆角与反模式清单。代码事实源:`src/theme/tokens.ts`(JS 侧唯一来源)与 `src/assets/main.css`(Tailwind `@theme`)。
|
||||
|
||||
## 基本规则
|
||||
|
||||
- 设计 token(色板、圆角、字体、间距)唯一来源是全局 CSS 变量(Tailwind `@theme`),Naive UI `themeOverrides` 从同一份取值;组件内禁止散落硬编码 hex。
|
||||
- Tailwind 工具类只用于布局、间距、排版;组件视觉(按钮/输入/表格)交给组件库主题,不用工具类二次描皮。
|
||||
- 间距遵循 4px 网格;圆角、阴影、配色遵守下方 token 与反模式清单。
|
||||
|
||||
## 风格特征
|
||||
|
||||
- **暖纸色底**:不用纯白,用象牙色 `#FAF9F5` 做主背景,靠 1px 细边框(hairline)和一层灰度差分层,几乎不用投影。
|
||||
- **单一强调色**:赤陶橙(terracotta)只出现在主按钮、激活态、品牌标记上,页面 95% 面积是黑白灰米。
|
||||
- **小圆角、扁平**:圆角 4–6px 量级;无渐变、无玻璃拟态、无 3D 浮雕、无大面积色块光晕。
|
||||
- **排版即装饰**:层级靠字号/字重/留白拉开;图标用细线性风格(lucide/tabler),不用 emoji 和彩色立体图标。
|
||||
- **克制的动效**:过渡 150–250ms、只做透明度/位移,无弹跳和视差。
|
||||
|
||||
## 官方色值(Anthropic 官方 brand-guidelines)
|
||||
|
||||
主色:
|
||||
|
||||
| Token | 色值 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| Dark | `#141413` | 主文本、深色背景 |
|
||||
| Light | `#FAF9F5` | 浅色背景、深底上的文本 |
|
||||
| Mid Gray | `#B0AEA5` | 次要元素、占位、禁用 |
|
||||
| Light Gray | `#E8E6DC` | 细微背景、分隔线、边框 |
|
||||
|
||||
强调色:
|
||||
|
||||
| Token | 色值 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| Orange | `#D97757` | 主强调(按钮、激活、链接 hover) |
|
||||
| Blue | `#6A9BCC` | 次强调(信息、链接) |
|
||||
| Green | `#788C5D` | 三级强调(成功) |
|
||||
|
||||
品牌橙近似变体(社区考证):`#C15F3C`(Crail,更深)与 `#CC785C`(Book Cloth),可用作橙色的 hover/active 深档。
|
||||
|
||||
## 管理面板适配 token
|
||||
|
||||
官方色板缺管理面板必需的语义色,按同色温补齐:
|
||||
|
||||
| 语义 | 建议值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 背景主 | `#FAF9F5` | 页面底 |
|
||||
| 背景面 | `#F0EEE6` | 侧栏、区块底(Light 与 Light Gray 之间) |
|
||||
| 卡片 | `#FFFFFF` | 白卡浮在暖底上,配 1px `#E8E6DC` 边框 |
|
||||
| 文本主/次 | `#141413` / `#6B6A63` | 次级文本由 Dark 与 Mid Gray 插值 |
|
||||
| 主强调 | `#D97757`,hover `#C15F3C` | |
|
||||
| 成功 / 信息 | `#788C5D` / `#6A9BCC` | 官方绿 / 蓝 |
|
||||
| 警告 | `#B8860B` 一档的暖赭 | 与暖色调和谐,避免高饱和黄 |
|
||||
| 危险 | `#BF4D43` 一档的砖红 | 避免纯红 `#FF0000` 系 |
|
||||
| 暗色模式 | 底 `#141413`、面 `#1F1E1D`、边框 `#33322E` | 文本反转用 Light |
|
||||
| 圆角 | 按钮/输入 4px,卡片 6px,最大不超过 8px | 拒绝大圆角 |
|
||||
| 阴影 | 无或 `0 1px 2px rgba(20,20,19,.05)` | 分层靠边框 |
|
||||
|
||||
## 字体
|
||||
|
||||
- 官方品牌字体 **Styrene**(无衬线)+ **Tiempos**(衬线)为商业授权,不可直接使用;官方开源替代:标题 **Poppins**、正文 **Lora**。
|
||||
- 本项目:UI 与数据全用无衬线(`Inter` 或 `Poppins`,中文回退 `PingFang SC` / `Noto Sans SC`);OCID、IP、日志等用等宽(`JetBrains Mono` / `ui-monospace`);衬线(Lora)只做登录页/大标题的编辑风点缀,可选。
|
||||
|
||||
## 反模式清单(设计稿与代码评审逐条对照)
|
||||
|
||||
大圆角(>8px 的按钮/卡片)、任何渐变(含品牌色渐变文字)、玻璃拟态/毛玻璃、霓虹光晕、彩色大投影、emoji 当图标、深紫深蓝"AI 感"配色、满屏色块卡片、弹跳动效。
|
||||
|
||||
## Common Mistake: NModal 宽度不能用 Tailwind class
|
||||
|
||||
**Symptom**:`<NModal preset="card" class="w-[480px]">` 弹窗实际渲染为全宽。
|
||||
|
||||
**Cause**:naive-ui 的样式为运行时注入(CSSinJS,`<style>` 追加在 head 尾部),其 `.n-card{width:100%}` 与 Tailwind utilities 同特异性但**后加载**,覆盖 `w-[480px]`。
|
||||
|
||||
**Fix / Prevention**:弹窗宽度一律用内联 style(优先级最高),与 FormModal.vue 同法:
|
||||
|
||||
```html
|
||||
<!-- Bad:被 naive-ui 运行时样式覆盖 -->
|
||||
<NModal preset="card" class="w-[480px] max-w-[92vw]">
|
||||
|
||||
<!-- Good -->
|
||||
<NModal preset="card" :style="{ width: '480px', maxWidth: 'calc(100vw - 24px)' }">
|
||||
```
|
||||
|
||||
## Common Mistake:编辑 SFC 时残留 `defineProps<...>()()` 双括号
|
||||
|
||||
**Symptom**:运行时 `ReferenceError: defineProps is not defined`(setup 内),但 `vue-tsc`、`vite build` 全绿——编译期完全静默。
|
||||
|
||||
**Cause**:对 `defineProps<{...}>()` 做字符串替换时旧串漏了尾部 `()`,替换后残留成 `()()`。`@vue/compiler-sfc` 只识别「宏调用语句」,对「调用宏返回值」的表达式不做宏转换,把 `defineProps` 原样保留成运行时标识符。
|
||||
|
||||
**Prevention**:替换 defineProps/defineEmits 行必须包含**完整语句(含结尾 `()`)**;宏相关改动后,不能只信 build 全绿,须实际打开一次使用该组件的页面(详情弹窗等惰性挂载组件尤其容易漏)。
|
||||
|
||||
## Common Mistake:scoped style 中 `:global(...)` 后接后代选择器会丢失后代
|
||||
|
||||
**Symptom**:`:global(html.dark) .totp-qr { ... }` 编译产物变成 `html.dark { ... }`——`.totp-qr` 整段丢失,规则错误落到 `html` 元素上(background/padding 直接作用于全页),目标元素完全不匹配。build 全绿、无告警。
|
||||
|
||||
**Cause**:`@vue/compiler-sfc` 的 scoped 转换对「`:global()` 后跟普通后代选择器」的组合处理不可靠,后代部分被丢弃而非追加 scope id。
|
||||
|
||||
**Fix / Prevention**:完整选择器整体放进 `:global()`:
|
||||
|
||||
```css
|
||||
/* Bad:编译后 .totp-qr 丢失,规则落到 html.dark 本身 */
|
||||
:global(html.dark) .totp-qr { background: #f5f4ed !important; }
|
||||
|
||||
/* Good:原样输出 html.dark .totp-qr(自命名 class 需保证全局唯一) */
|
||||
:global(html.dark .totp-qr) { background: #f5f4ed !important; }
|
||||
```
|
||||
|
||||
验证方法:build 后 `grep -o 'html\.dark[^}]*}' dist/assets/<view>-*.css` 核对编译产物选择器,或线上 DevTools 看 computed style 是否命中。
|
||||
|
||||
## 组件速查:NQrCode 去白底
|
||||
|
||||
NQrCode 自带 inline `background-color:#FFF; padding:12px`(props 可控)。两主题都不垫任何色块的方案:`:padding="0" background-color="transparent"` + `:color="app.dark ? '#f5f4ed' : '#141413'"`——暗色下反色渲染(浅模块透明底),主流扫码器(iOS 相机 / Google Lens / 新版 ML Kit)可识别,扫不动时弹窗内的手动密钥是兜底。color 是响应式 prop,切主题自动重绘。(历史方案「html.dark 下垫 #f5f4ed 浅底」因用户不接受色块框已废弃。)
|
||||
@@ -0,0 +1,51 @@
|
||||
# Type Safety
|
||||
|
||||
> Type safety patterns in this project.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<!--
|
||||
Document your project's type safety conventions here.
|
||||
|
||||
Questions to answer:
|
||||
- What type system do you use?
|
||||
- How are types organized?
|
||||
- What validation library do you use?
|
||||
- How do you handle type inference?
|
||||
-->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Type Organization
|
||||
|
||||
<!-- Where types are defined, shared types vs local types -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
<!-- Type utilities, generics, type guards -->
|
||||
|
||||
(To be filled by the team)
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns
|
||||
|
||||
<!-- any, type assertions, etc. -->
|
||||
|
||||
(To be filled by the team)
|
||||
@@ -0,0 +1,16 @@
|
||||
# TypeScript 与 Vue 组件规范
|
||||
|
||||
## TypeScript
|
||||
|
||||
- 开启 `strict`;禁止 `any`,未知类型用 `unknown` 后收窄。
|
||||
- 对象形状优先 `interface`,联合/工具类型用 `type`;类型导入写 `import type`。
|
||||
- 与后端交互的 DTO 类型集中在 `types/`,字段与 `docs/API接口文档.md` 一一对应,不在组件里手写内联响应类型。
|
||||
- 用 `const` 对象 + `as const` 代替 `enum`。
|
||||
|
||||
## Vue 组件
|
||||
|
||||
- 一律 `<script setup lang="ts">` 组合式 API;组件名 PascalCase 且多词(`InstanceTable`,避免与 HTML 元素冲突)。
|
||||
- `defineProps`/`defineEmits` 写完整类型;props 只读,不在子组件内改。
|
||||
- `v-for` 必须带 `key`,且不与 `v-if` 写在同一元素上。
|
||||
- 组件内样式一律 `scoped`;跨组件复用样式上提到全局 token 或工具类。
|
||||
- 复用逻辑抽 composable(`useXxx` 命名,放 `composables/`);单文件组件函数遵循 ≤30 行的项目约定。
|
||||
@@ -0,0 +1,223 @@
|
||||
# Code Reuse Thinking Guide
|
||||
|
||||
> **Purpose**: Stop and think before creating new code - does it already exist?
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Duplicated code is the #1 source of inconsistency bugs.**
|
||||
|
||||
When you copy-paste or rewrite existing logic:
|
||||
- Bug fixes don't propagate
|
||||
- Behavior diverges over time
|
||||
- Codebase becomes harder to understand
|
||||
|
||||
---
|
||||
|
||||
## Before Writing New Code
|
||||
|
||||
### Step 1: Search First
|
||||
|
||||
```bash
|
||||
# Search for similar function names
|
||||
grep -r "functionName" .
|
||||
|
||||
# Search for similar logic
|
||||
grep -r "keyword" .
|
||||
```
|
||||
|
||||
### Step 2: Ask These Questions
|
||||
|
||||
| Question | If Yes... |
|
||||
|----------|-----------|
|
||||
| Does a similar function exist? | Use or extend it |
|
||||
| Is this pattern used elsewhere? | Follow the existing pattern |
|
||||
| Could this be a shared utility? | Create it in the right place |
|
||||
| Am I copying code from another file? | **STOP** - extract to shared |
|
||||
|
||||
---
|
||||
|
||||
## Common Duplication Patterns
|
||||
|
||||
### Pattern 1: Copy-Paste Functions
|
||||
|
||||
**Bad**: Copying a validation function to another file
|
||||
|
||||
**Good**: Extract to shared utilities, import where needed
|
||||
|
||||
### Pattern 2: Similar Components
|
||||
|
||||
**Bad**: Creating a new component that's 80% similar to existing
|
||||
|
||||
**Good**: Extend existing component with props/variants
|
||||
|
||||
### Pattern 3: Repeated Constants
|
||||
|
||||
**Bad**: Defining the same constant in multiple files
|
||||
|
||||
**Good**: Single source of truth, import everywhere
|
||||
|
||||
### Pattern 4: Repeated Payload Field Extraction
|
||||
|
||||
**Bad**: Multiple consumers cast the same JSON/event fields locally:
|
||||
|
||||
```typescript
|
||||
const description = (ev as { description?: string }).description;
|
||||
const context = (ev as { context?: ContextEntry[] }).context;
|
||||
```
|
||||
|
||||
This is duplicated contract logic even when the code is only two lines. Each
|
||||
consumer now has its own definition of what a valid payload means.
|
||||
|
||||
**Good**: Put the decoder, type guard, or projection next to the data owner:
|
||||
|
||||
```typescript
|
||||
if (isThreadEvent(ev)) {
|
||||
renderThreadEvent(ev);
|
||||
}
|
||||
```
|
||||
|
||||
**Rule**: If the same untyped payload field is read in 2+ places, create a
|
||||
shared type guard / normalizer / projection before adding a third reader.
|
||||
|
||||
---
|
||||
|
||||
## When to Abstract
|
||||
|
||||
**Abstract when**:
|
||||
- Same code appears 3+ times
|
||||
- Logic is complex enough to have bugs
|
||||
- Multiple people might need this
|
||||
|
||||
**Don't abstract when**:
|
||||
- Only used once
|
||||
- Trivial one-liner
|
||||
- Abstraction would be more complex than duplication
|
||||
|
||||
---
|
||||
|
||||
## After Batch Modifications
|
||||
|
||||
When you've made similar changes to multiple files:
|
||||
|
||||
1. **Review**: Did you catch all instances?
|
||||
2. **Search**: Run grep to find any missed
|
||||
3. **Consider**: Should this be abstracted?
|
||||
|
||||
### Reducers Should Use Exhaustive Structure
|
||||
|
||||
When state is derived from action-like values (`action`, `kind`, `status`,
|
||||
`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
|
||||
|
||||
```typescript
|
||||
// BAD - action-specific state transitions are hard to audit
|
||||
if (action === "opened") { ... }
|
||||
else if (action === "comment") { ... }
|
||||
else if (action === "status") { ... }
|
||||
|
||||
// GOOD - one reducer owns the transition table
|
||||
switch (event.action) {
|
||||
case "opened":
|
||||
...
|
||||
return;
|
||||
case "comment":
|
||||
...
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
This matters when the event log is the source of truth. A reducer is the
|
||||
documented replay model; display code and commands should not duplicate pieces
|
||||
of that replay model.
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Commit
|
||||
|
||||
- [ ] Searched for existing similar code
|
||||
- [ ] No copy-pasted logic that should be shared
|
||||
- [ ] No repeated untyped payload field extraction outside a shared decoder
|
||||
- [ ] Constants defined in one place
|
||||
- [ ] Similar patterns follow same structure
|
||||
- [ ] Reducer/action transitions live in one reducer or command dispatcher
|
||||
|
||||
---
|
||||
|
||||
## Gotcha: Python if/elif/else Exhaustive Check
|
||||
|
||||
**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
|
||||
|
||||
**Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
|
||||
|
||||
**Example** (`cli_adapter.py`):
|
||||
```python
|
||||
# BAD: "gemini" falls through to else, returns "claude"
|
||||
@property
|
||||
def cli_name(self) -> str:
|
||||
if self.platform == "opencode":
|
||||
return "opencode"
|
||||
else:
|
||||
return "claude" # gemini silently gets "claude"!
|
||||
|
||||
# GOOD: explicit branch for every platform
|
||||
@property
|
||||
def cli_name(self) -> str:
|
||||
if self.platform == "opencode":
|
||||
return "opencode"
|
||||
elif self.platform == "gemini":
|
||||
return "gemini"
|
||||
else:
|
||||
return "claude"
|
||||
```
|
||||
|
||||
**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
|
||||
|
||||
---
|
||||
|
||||
## Gotcha: Asymmetric Mechanisms Producing Same Output
|
||||
|
||||
**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
|
||||
|
||||
**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
|
||||
|
||||
**Prevention**:
|
||||
- **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
|
||||
- **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
|
||||
- When migrating directory structures, search for ALL code paths that reference the old structure
|
||||
|
||||
**Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
|
||||
|
||||
---
|
||||
|
||||
## Template File Registration (Trellis-specific)
|
||||
|
||||
When adding new files to `src/templates/trellis/scripts/`:
|
||||
|
||||
**Single registration point**: `src/templates/trellis/index.ts`
|
||||
|
||||
1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
|
||||
2. Add to `getAllScripts()` Map
|
||||
|
||||
That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
|
||||
|
||||
**Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
|
||||
|
||||
**History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
|
||||
|
||||
### Quick Checklist for New Scripts
|
||||
|
||||
```bash
|
||||
# After adding a new .py file, verify it's in getAllScripts():
|
||||
grep -l "newFileName" src/templates/trellis/index.ts # Should match
|
||||
```
|
||||
|
||||
### Template Sync Convention
|
||||
|
||||
`.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
|
||||
|
||||
```bash
|
||||
rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
|
||||
```
|
||||
|
||||
**Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.
|
||||
@@ -0,0 +1,327 @@
|
||||
# Cross-Layer Thinking Guide
|
||||
|
||||
> **Purpose**: Think through data flow across layers before implementing.
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Most bugs happen at layer boundaries**, not within layers.
|
||||
|
||||
Common cross-layer bugs:
|
||||
|
||||
- API returns format A, frontend expects format B
|
||||
- Database stores X, service transforms to Y, but loses data
|
||||
- Multiple layers implement the same logic differently
|
||||
|
||||
---
|
||||
|
||||
## Before Implementing Cross-Layer Features
|
||||
|
||||
### Step 1: Map the Data Flow
|
||||
|
||||
Draw out how data moves:
|
||||
|
||||
```
|
||||
Source → Transform → Store → Retrieve → Transform → Display
|
||||
```
|
||||
|
||||
For each arrow, ask:
|
||||
|
||||
- What format is the data in?
|
||||
- What could go wrong?
|
||||
- Who is responsible for validation?
|
||||
|
||||
### Step 2: Identify Boundaries
|
||||
|
||||
| Boundary | Common Issues |
|
||||
| --------------------- | --------------------------------- |
|
||||
| API ↔ Service | Type mismatches, missing fields |
|
||||
| Service ↔ Database | Format conversions, null handling |
|
||||
| Backend ↔ Frontend | Serialization, date formats |
|
||||
| Component ↔ Component | Props shape changes |
|
||||
|
||||
### Step 3: Define Contracts
|
||||
|
||||
For each boundary:
|
||||
|
||||
- What is the exact input format?
|
||||
- What is the exact output format?
|
||||
- What errors can occur?
|
||||
|
||||
---
|
||||
|
||||
## Common Cross-Layer Mistakes
|
||||
|
||||
### Mistake 1: Implicit Format Assumptions
|
||||
|
||||
**Bad**: Assuming date format without checking
|
||||
|
||||
**Good**: Explicit format conversion at boundaries
|
||||
|
||||
### Mistake 2: Scattered Validation
|
||||
|
||||
**Bad**: Validating the same thing in multiple layers
|
||||
|
||||
**Good**: Validate once at the entry point
|
||||
|
||||
### Mistake 3: Leaky Abstractions
|
||||
|
||||
**Bad**: Component knows about database schema
|
||||
|
||||
**Good**: Each layer only knows its neighbors
|
||||
|
||||
### Mistake 4: Every Consumer Parses The Same Payload
|
||||
|
||||
**Bad**: A command reads JSONL events and casts fields inline:
|
||||
|
||||
```typescript
|
||||
const thread = (ev as { thread?: string }).thread;
|
||||
const labels = (ev as { labels?: string[] }).labels;
|
||||
```
|
||||
|
||||
This looks local, but it means every consumer owns a private version of the
|
||||
event contract. The next field change will update one command and miss another.
|
||||
|
||||
**Good**: Decode once at the event boundary, then export typed projections:
|
||||
|
||||
```typescript
|
||||
if (!isThreadEvent(ev)) return false;
|
||||
return ev.thread === filter.thread;
|
||||
```
|
||||
|
||||
**Rule**: For append-only logs, JSON streams, RPC payloads, or config files,
|
||||
create one owner for:
|
||||
|
||||
- event / payload type definitions
|
||||
- type guards and normalization from `unknown`
|
||||
- metadata projections used by UI commands
|
||||
- reducers that replay state from the source of truth
|
||||
|
||||
Rendering code may format fields, but it must not redefine the payload contract.
|
||||
|
||||
---
|
||||
|
||||
## Checklist for Cross-Layer Features
|
||||
|
||||
Before implementation:
|
||||
|
||||
- [ ] Mapped the complete data flow
|
||||
- [ ] Identified all layer boundaries
|
||||
- [ ] Defined format at each boundary
|
||||
- [ ] Decided where validation happens
|
||||
|
||||
After implementation:
|
||||
|
||||
- [ ] Tested with edge cases (null, empty, invalid)
|
||||
- [ ] Verified error handling at each boundary
|
||||
- [ ] Checked data survives round-trip
|
||||
- [ ] Checked that consumers import shared decoders / projections instead of
|
||||
casting payload fields locally
|
||||
- [ ] Checked that derived state points back to the source event identifier
|
||||
(`seq`, `id`, `version`) instead of inventing a second cursor
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Template Consistency
|
||||
|
||||
In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
|
||||
|
||||
### Checklist: After Modifying Any Command Template
|
||||
|
||||
- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
|
||||
- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
|
||||
- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
|
||||
- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
|
||||
|
||||
**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
|
||||
|
||||
---
|
||||
|
||||
## Generated Runtime Template Upgrade Consistency
|
||||
|
||||
Some generated files are both documentation and runtime input. In Trellis,
|
||||
`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
|
||||
SessionStart filters, and per-turn hooks. Template changes must be validated
|
||||
against both fresh init and upgrade paths.
|
||||
|
||||
### Checklist: After Modifying A Runtime-Parsed Template
|
||||
|
||||
- [ ] Identify every runtime parser that reads the template, not just the file
|
||||
writer that installs it
|
||||
- [ ] Check whether relevant syntax lives outside obvious managed regions
|
||||
such as tag blocks
|
||||
- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
|
||||
the older `.trellis/.version`
|
||||
- [ ] Add an upgrade regression using an older pristine template fixture, then
|
||||
assert the installed file reaches the current packaged shape
|
||||
- [ ] Update the backend spec that owns the runtime contract
|
||||
|
||||
---
|
||||
|
||||
## Versioned Documentation Boundary
|
||||
|
||||
Versioned documentation is a cross-layer boundary: source paths, `docs.json`
|
||||
version routing, and the rendered version selector must all describe the same
|
||||
release line.
|
||||
|
||||
### Checklist: Before Editing Versioned Docs
|
||||
|
||||
- [ ] Identify the target release line: stable, beta, or RC
|
||||
- [ ] Verify the edited MDX path matches that line:
|
||||
- stable: `docs-site/{start,advanced,...}` and `docs-site/zh/{start,advanced,...}`
|
||||
- beta: `docs-site/beta/**` and `docs-site/zh/beta/**`
|
||||
- RC: `docs-site/rc/**` and `docs-site/zh/rc/**`
|
||||
- [ ] Verify `docs.json` navigation points the version label to the same paths
|
||||
- [ ] Grep the opposite tree for release-line-specific terms before committing
|
||||
- [ ] Treat beta content appearing under root release paths as a source-path bug,
|
||||
not a rendering bug
|
||||
|
||||
**Real-world example**: A beta-only task workflow change documented
|
||||
`prd.md` + `design.md` + `implement.md`, task-creation consent, and Codex
|
||||
mode banners under root `start/` and `advanced/` paths. The docs site then
|
||||
served 0.6 beta behavior under the Release selector. The fix was to restore root
|
||||
release docs, move the 0.6 content to `beta/` and `zh/beta/`, and add a grep
|
||||
audit for beta markers against the root release tree.
|
||||
|
||||
**Real-world example**: Codex inline mode changed workflow platform markers from
|
||||
`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
|
||||
`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
|
||||
`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
|
||||
markers outside those blocks. Result: upgraded projects got new hook scripts
|
||||
but old workflow routing, so `get_context.py --mode phase --platform codex`
|
||||
could return empty Phase 2.1 detail.
|
||||
|
||||
---
|
||||
|
||||
## Mode-Detection Probe Checklist
|
||||
|
||||
When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
|
||||
|
||||
### Before implementing:
|
||||
|
||||
- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
|
||||
- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
|
||||
- [ ] Transient errors **abort or retry**, never silently switch modes
|
||||
- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
|
||||
- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
|
||||
|
||||
### After implementing:
|
||||
|
||||
- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
|
||||
- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
|
||||
- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
|
||||
- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
|
||||
- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
|
||||
|
||||
**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
|
||||
|
||||
**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Template Consistency
|
||||
|
||||
In Trellis, command templates (e.g., `record-session.md`) exist in **multiple platforms** with identical or near-identical content. This is a cross-layer boundary.
|
||||
|
||||
### Checklist: After Modifying Any Command Template
|
||||
|
||||
- [ ] Find all platforms with the same command: `find src/templates/*/commands/trellis/ -name "<command>.*"`
|
||||
- [ ] Update all platform copies (Markdown `.md` and TOML `.toml`)
|
||||
- [ ] For Gemini TOML: adapt line continuations (`\\` vs `\`) and triple-quoted strings
|
||||
- [ ] Run `/trellis:check-cross-layer` to verify nothing was missed
|
||||
|
||||
**Real-world example**: Updated `record-session.md` in Claude to use `--mode record`, but forgot iFlow, Kilo, OpenCode, and Gemini — caught by cross-layer check.
|
||||
|
||||
---
|
||||
|
||||
## Generated Runtime Template Upgrade Consistency
|
||||
|
||||
Some generated files are both documentation and runtime input. In Trellis,
|
||||
`.trellis/workflow.md` is parsed by `get_context.py`, `workflow_phase.py`,
|
||||
SessionStart filters, and per-turn hooks. Template changes must be validated
|
||||
against both fresh init and upgrade paths.
|
||||
|
||||
### Checklist: After Modifying A Runtime-Parsed Template
|
||||
|
||||
- [ ] Identify every runtime parser that reads the template, not just the file
|
||||
writer that installs it
|
||||
- [ ] Check whether relevant syntax lives outside obvious managed regions
|
||||
such as tag blocks
|
||||
- [ ] Verify fresh `init` output and a versioned `update` scenario that writes
|
||||
the older `.trellis/.version`
|
||||
- [ ] Add an upgrade regression using an older pristine template fixture, then
|
||||
assert the installed file reaches the current packaged shape
|
||||
- [ ] Update the backend spec that owns the runtime contract
|
||||
|
||||
**Real-world example**: Codex inline mode changed workflow platform markers from
|
||||
`[Codex]` / `[Kilo, Antigravity, Windsurf]` to `[codex-sub-agent]` /
|
||||
`[codex-inline, Kilo, Antigravity, Windsurf]`. Fresh init was correct, but
|
||||
`trellis update` only merged `[workflow-state:*]` blocks and preserved stale
|
||||
markers outside those blocks. Result: upgraded projects got new hook scripts
|
||||
but old workflow routing, so `get_context.py --mode phase --platform codex`
|
||||
could return empty Phase 2.1 detail.
|
||||
|
||||
---
|
||||
|
||||
## Mode-Detection Probe Checklist
|
||||
|
||||
When a CLI auto-detects a mode by probing a remote resource (e.g., checking if `index.json` exists to decide marketplace vs direct download):
|
||||
|
||||
### Before implementing:
|
||||
- [ ] Probe runs in **ALL** code paths that use the result (interactive, `-y`, `--flag` combos)
|
||||
- [ ] 404 vs transient error are distinguished — don't treat both as "not found"
|
||||
- [ ] Transient errors **abort or retry**, never silently switch modes
|
||||
- [ ] Shared state (caches, prefetched data) is **reset** when context changes (e.g., user switches source)
|
||||
- [ ] **Shortcut paths** (e.g., `--template` skipping picker) must have the same error-handling quality as the probed path — check that downstream functions don't call catch-all wrappers
|
||||
|
||||
### After implementing:
|
||||
- [ ] Trace every path from probe result to the mode-decision branch — no fallthrough
|
||||
- [ ] External format contracts (giget URI, raw URLs) are tested or at least documented as comments
|
||||
- [ ] Metadata reads consume a complete response or use a streaming parser — never parse a fixed-size prefix as full JSON
|
||||
- [ ] When reconstructing a composite identifier from parsed parts, verify **all** fields are included and in the **correct position** (e.g., `provider:repo/path#ref` not `provider:repo#ref/path`)
|
||||
- [ ] Verify that **action functions** called after a shortcut don't internally use the old catch-all fetch — they must use the probe-quality variant when error distinction matters
|
||||
|
||||
**Real-world example**: Custom registry flow had 8 bugs across 3 review rounds: (1) probe only ran in interactive mode, (2) transient errors fell through to wrong mode, (3) giget URI had `#ref` in wrong position, (4) prefetched templates leaked across source switches, (5) `--template` shortcut bypassed probe but `downloadTemplateById` internally used catch-all `fetchTemplateIndex`, turning timeouts into "Template not found".
|
||||
|
||||
**Real-world example**: Agent-session update hints fetched npm `latest` metadata with `response.read(4096)` and then parsed it as complete JSON. The `@mindfoldhq/trellis` package metadata exceeded 4 KB, so the JSON was truncated, parse failed silently, and the first session injection showed no update hint. Fix: read the complete response before parsing, and add a regression where `version` is followed by an 8 KB metadata tail.
|
||||
|
||||
---
|
||||
|
||||
## When to Create Flow Documentation
|
||||
|
||||
Create detailed flow docs when:
|
||||
|
||||
- Feature spans 3+ layers
|
||||
- Multiple teams are involved
|
||||
- Data format is complex
|
||||
- Feature has caused bugs before
|
||||
|
||||
---
|
||||
|
||||
## Event Log / Projection Boundary
|
||||
|
||||
Append-only logs are cross-layer contracts. A single event travels through:
|
||||
|
||||
```
|
||||
CLI input → event writer → events.jsonl → reader → filter → reducer → display
|
||||
```
|
||||
|
||||
### Checklist: After Adding A New Event Kind Or Field
|
||||
|
||||
- [ ] Add the event kind to the central event taxonomy
|
||||
- [ ] Add a typed event variant or type guard at the event layer
|
||||
- [ ] Add normalization helpers for array/object fields that come from
|
||||
user input or JSON
|
||||
- [ ] Keep `seq` / `id` assignment in the event writer only
|
||||
- [ ] Make filters and reducers consume the typed event guard, not local casts
|
||||
- [ ] Make display code consume reducer output or typed events, not raw JSON
|
||||
- [ ] Add at least one regression that proves history replay and live filtering
|
||||
use the same filter model
|
||||
|
||||
**Real-world example**: Thread channels added `kind: "thread"`, `description`,
|
||||
`context`, labels, and `lastSeq`. The first implementation replayed thread
|
||||
state correctly, but several commands still re-parsed event payload fields with
|
||||
local casts. The fix was to make the core event layer own `ThreadChannelEvent`
|
||||
and `isThreadEvent`, make `reduceChannelMetadata` the only channel metadata
|
||||
projection, and make `reduceThreads` the only thread replay reducer.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Claude Design 设计稿工作流
|
||||
|
||||
> 设计稿在 **Claude Design**(claude.ai/design)中产出与评审:云端项目制文件工作区,Claude 通过 MCP 工具直接读写项目文件,用户在网页编辑器中实时查看、点选修改、评论,双方操作同一份文件。
|
||||
|
||||
## 产物形态
|
||||
|
||||
- 设计稿是 **`.dc.html`(Design Components)文件**:HTML 承载视觉,`<x-dc>` 模板 + `support.js` 运行时(服务端下发,不手写)让用户能在 Claude Design 编辑器里点选任意元素直接改文案/样式,而不是只读预览。
|
||||
- 交互原型(视图切换、筛选、hover 态)由文件内的逻辑类驱动,单文件即可承载多视图的完整面板原型。
|
||||
- 设计 token 不依赖平台 design system,以 [styling-design-tokens.md](../frontend/styling-design-tokens.md) 的 Anthropic 风 token 直接内嵌为设计稿的样式事实源。
|
||||
|
||||
## 工作流
|
||||
|
||||
| 阶段 | 动作 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| ① 加载规范 | `get_claude_design_prompt` | 每次会话先加载平台设计规范(.dc.html 约定、反 AI-slop 内容准则),再动手 |
|
||||
| ② 建项目 | `create_project` | 一个设计主题一个项目;返回 claude.ai/design 项目链接 |
|
||||
| ③ 写运行时 | `create_support_js` | 每个含 .dc.html 的目录一次,服务端写入当前 dc-runtime |
|
||||
| ④ 声明与写入 | `finalize_plan` → `write_files` | 先声明本批要写的路径拿 plan_token;写入时带 etag(if_match)防止覆盖用户在编辑器里的并发修改 |
|
||||
| ⑤ 渲染验证 | `render_preview` + playwright-cli | 渲染循环:截图 1440×900、查 console 错误/404/空白 → 修复 → 重渲,直到干净;再以"新眼睛"逐条核对需求与反模式清单 |
|
||||
| ⑥ 交付评审 | 分享 claude.ai/design 页面链接 | 用户在编辑器里直接批注/修改;`?embed=1` 链接可实时看 Claude 的每次写入 |
|
||||
|
||||
## 协作与边界
|
||||
|
||||
- **并发安全**:用户可能同时在编辑器里改文件,所有写入必须带上次读到的 etag,冲突时以用户改动为基准重新套用变更,绝不无条件覆盖。
|
||||
- **链接纪律**:交付给人的永远是 claude.ai/design 链接;`serve_url`(claudeusercontent.com)是带项目令牌的短时链接,仅供自动化浏览器验证,不得外发。
|
||||
- **平台边界**:Claude Design 没有本地 skill/plugin 市场与内部生成 agent,设计由当前会话直接产出;风格底座与评审职责由 token 清单(含反模式)与渲染验证循环承接。
|
||||
- **导出衔接**:定稿 .dc.html 即结构化 HTML/CSS,实现阶段按 `.trellis/frontend/` 前端规范翻译成 Vue SFC + Naive UI themeOverrides,token 一一对应。
|
||||
@@ -0,0 +1,97 @@
|
||||
# Thinking Guides
|
||||
|
||||
> **Purpose**: Expand your thinking to catch things you might not have considered.
|
||||
|
||||
---
|
||||
|
||||
## Why Thinking Guides?
|
||||
|
||||
**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
|
||||
|
||||
- Didn't think about what happens at layer boundaries → cross-layer bugs
|
||||
- Didn't think about code patterns repeating → duplicated code everywhere
|
||||
- Didn't think about edge cases → runtime errors
|
||||
- Didn't think about future maintainers → unreadable code
|
||||
|
||||
These guides help you **ask the right questions before coding**.
|
||||
|
||||
---
|
||||
|
||||
## Available Guides
|
||||
|
||||
| Guide | Purpose | When to Use |
|
||||
|-------|---------|-------------|
|
||||
| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
|
||||
| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Thinking Triggers
|
||||
|
||||
### When to Think About Cross-Layer Issues
|
||||
|
||||
- [ ] Feature touches 3+ layers (API, Service, Component, Database)
|
||||
- [ ] Data format changes between layers
|
||||
- [ ] Multiple consumers need the same data
|
||||
- [ ] You're not sure where to put some logic
|
||||
- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
|
||||
- [ ] UI / command code starts casting raw payload fields directly
|
||||
|
||||
→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
|
||||
|
||||
### When to Think About Code Reuse
|
||||
|
||||
- [ ] You're writing similar code to something that exists
|
||||
- [ ] You see the same pattern repeated 3+ times
|
||||
- [ ] You're adding a new field to multiple places
|
||||
- [ ] **You're modifying any constant or config**
|
||||
- [ ] **You're creating a new utility/helper function** ← Search first!
|
||||
- [ ] Two files read the same untyped payload field with local casts
|
||||
- [ ] Multiple branches update the same derived state from `kind` / `action`
|
||||
|
||||
→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
|
||||
|
||||
### When Verifying AI Cross-Review Results
|
||||
|
||||
- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
|
||||
- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
|
||||
- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
|
||||
- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
|
||||
|
||||
**Common AI reviewer false-positive patterns**:
|
||||
1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
|
||||
2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
|
||||
3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
|
||||
|
||||
**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
|
||||
|
||||
---
|
||||
|
||||
## Pre-Modification Rule (CRITICAL)
|
||||
|
||||
> **Before changing ANY value, ALWAYS search first!**
|
||||
|
||||
```bash
|
||||
# Search for the value you're about to change
|
||||
grep -r "value_to_change" .
|
||||
```
|
||||
|
||||
This single habit prevents most "forgot to update X" bugs.
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Directory
|
||||
|
||||
1. **Before coding**: Skim the relevant thinking guide
|
||||
2. **During coding**: If something feels repetitive or complex, check the guides
|
||||
3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a new "didn't think of that" moment? Add it to the relevant guide.
|
||||
|
||||
---
|
||||
|
||||
**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
|
||||
@@ -0,0 +1,708 @@
|
||||
# Development Workflow
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Plan before code** — figure out what to do before you start
|
||||
2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
|
||||
3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
|
||||
4. **Incremental development** — one task at a time
|
||||
5. **Capture learnings** — after each task, review and write new knowledge back to spec
|
||||
|
||||
---
|
||||
|
||||
## Trellis System
|
||||
|
||||
### Developer Identity
|
||||
|
||||
On first use, initialize your identity:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/init_developer.py <your-name>
|
||||
```
|
||||
|
||||
Creates `.trellis/.developer` (gitignored) + `.trellis/workspace/<your-name>/`.
|
||||
|
||||
### Spec System
|
||||
|
||||
`.trellis/spec/` holds coding guidelines organized by package and layer.
|
||||
|
||||
- `.trellis/spec/<package>/<layer>/index.md` — entry point with **Pre-Development Checklist** + **Quality Check**. Actual guidelines live in the `.md` files it points to.
|
||||
- `.trellis/spec/guides/index.md` — cross-package thinking guides.
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages # list packages / layers
|
||||
```
|
||||
|
||||
**When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision.
|
||||
|
||||
### Task System
|
||||
|
||||
Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `task.json`, `prd.md`, optional `design.md`, optional `implement.md`, optional `research/`, and context manifests (`implement.jsonl`, `check.jsonl`) for sub-agent-capable platforms.
|
||||
|
||||
```bash
|
||||
# Task lifecycle
|
||||
python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
|
||||
python3 ./.trellis/scripts/task.py start <name> # set active task (session-scoped when available)
|
||||
python3 ./.trellis/scripts/task.py current --source # show active task and source
|
||||
python3 ./.trellis/scripts/task.py finish # clear active task (triggers after_finish hooks)
|
||||
python3 ./.trellis/scripts/task.py archive <name> # move to archive/{year-month}/
|
||||
python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
|
||||
python3 ./.trellis/scripts/task.py list-archive
|
||||
|
||||
# Code-spec context (injected into implement/check agents via JSONL).
|
||||
# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable
|
||||
# platforms; the AI curates real spec + research entries during planning when needed.
|
||||
python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
|
||||
python3 ./.trellis/scripts/task.py list-context <name> [action]
|
||||
python3 ./.trellis/scripts/task.py validate <name>
|
||||
|
||||
# Task metadata
|
||||
python3 ./.trellis/scripts/task.py set-branch <name> <branch>
|
||||
python3 ./.trellis/scripts/task.py set-base-branch <name> <branch> # PR target
|
||||
python3 ./.trellis/scripts/task.py set-scope <name> <scope>
|
||||
|
||||
# Hierarchy (parent/child)
|
||||
python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
|
||||
python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
|
||||
|
||||
# PR creation
|
||||
python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run]
|
||||
```
|
||||
|
||||
> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list.
|
||||
|
||||
**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, there is no active task and `task.py start` fails with a session identity hint. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
|
||||
|
||||
### Workspace System
|
||||
|
||||
Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`.
|
||||
|
||||
- `journal-N.md` — session log. **Max 2000 lines per file**; a new `journal-(N+1).md` is auto-created when exceeded.
|
||||
- `index.md` — personal index (total sessions, last active).
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary"
|
||||
```
|
||||
|
||||
### Context Script
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py # full session runtime
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages # available packages + spec layers
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y> # detailed guide for a workflow step
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<!--
|
||||
WORKFLOW-STATE BREADCRUMB CONTRACT (read this before editing the tag blocks below)
|
||||
|
||||
The [workflow-state:STATUS] blocks embedded in the ## Phase Index section
|
||||
below are the SINGLE source of truth for the per-turn `<workflow-state>`
|
||||
breadcrumb that every supported AI platform's UserPromptSubmit hook
|
||||
reads. inject-workflow-state.py (Python platforms) and
|
||||
inject-workflow-state.js (OpenCode plugin) only parse them — there is no
|
||||
fallback dict baked into the scripts after v0.5.0-rc.0.
|
||||
|
||||
STATUS charset: [A-Za-z0-9_-]+. When the hook can't find a tag, it
|
||||
degrades to a generic "Refer to workflow.md for current step." line —
|
||||
intentionally visible so users notice and fix a broken workflow.md.
|
||||
|
||||
INVARIANT (test/regression.test.ts):
|
||||
Every workflow-walkthrough step marked `[required · once]` must have a
|
||||
matching enforcement line in its phase's [workflow-state:*] block. The
|
||||
breadcrumb is the only per-turn channel; if a mandatory step isn't
|
||||
mentioned there, the AI silently skips it (Phase 1 planning gate
|
||||
skip and Phase 3.4 commit skip both manifested via this gap).
|
||||
|
||||
TAG ↔ PHASE scoping:
|
||||
[workflow-state:no_task] → no active task; before Phase 1
|
||||
[workflow-state:planning] → all of Phase 1 (status='planning')
|
||||
[workflow-state:planning-inline] → Codex inline variant of Phase 1
|
||||
[workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4
|
||||
(status stays 'in_progress' from
|
||||
task.py start until task.py archive)
|
||||
[workflow-state:in_progress-inline] → Codex inline variant of Phase 2/3
|
||||
[workflow-state:completed] → currently DEAD: cmd_archive flips
|
||||
status and moves the dir in the same
|
||||
call, so the resolver loses the
|
||||
pointer (block kept for a future
|
||||
explicit in_progress→completed
|
||||
transition)
|
||||
|
||||
Editing checklist:
|
||||
- When you change a [workflow-state:STATUS] block, also check the
|
||||
matching phase's `[required · once]` walkthrough steps for sync
|
||||
- Run `trellis update` after editing to push the new bodies to
|
||||
downstream user projects (block-level managed replacement)
|
||||
- Full runtime contract:
|
||||
.trellis/spec/cli/backend/workflow-state-contract.md
|
||||
-->
|
||||
|
||||
## Phase Index
|
||||
|
||||
```
|
||||
Phase 1: Plan → classify, get task-creation consent, then write planning artifacts
|
||||
Phase 2: Execute → implement only after task status is in_progress
|
||||
Phase 3: Finish → verify, update spec, commit, and wrap up
|
||||
```
|
||||
|
||||
### Request Triage
|
||||
|
||||
- Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
|
||||
- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
|
||||
- User approval to create a task is not approval to start implementation. Planning still happens first.
|
||||
|
||||
### Planning Artifacts
|
||||
|
||||
- `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
|
||||
- `design.md` — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape.
|
||||
- `implement.md` — execution plan for complex tasks: ordered checklist, validation commands, review gates, and rollback points.
|
||||
- `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`.
|
||||
- Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
|
||||
|
||||
### Parent / Child Task Trees
|
||||
|
||||
Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work.
|
||||
|
||||
Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child `prd.md` / `implement.md` and keep each child's acceptance criteria testable.
|
||||
|
||||
Create new children with `task.py create "<title>" --slug <name> --parent <parent-dir>`. Link existing tasks with `task.py add-subtask <parent> <child>`, and unlink mistakes with `task.py remove-subtask <parent> <child>`.
|
||||
|
||||
<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
|
||||
|
||||
[workflow-state:no_task]
|
||||
No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
|
||||
Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
|
||||
Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
|
||||
[/workflow-state:no_task]
|
||||
|
||||
### Phase 1: Plan
|
||||
- 1.0 Create task `[required · once]` (only after task-creation consent)
|
||||
- 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
|
||||
- 1.2 Research `[optional · repeatable]`
|
||||
- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix (sub-agent-dispatch platforms only; inline platforms skip)
|
||||
- 1.4 Activate task `[required · once]` (review gate, then `task.py start`; status → in_progress)
|
||||
- 1.5 Completion criteria
|
||||
|
||||
<!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') -->
|
||||
|
||||
[workflow-state:planning]
|
||||
Load `trellis-brainstorm`; stay in planning.
|
||||
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
|
||||
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
|
||||
Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start.
|
||||
[/workflow-state:planning]
|
||||
|
||||
<!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline.
|
||||
Codex-only opt-in alternate to [workflow-state:planning]. The main agent
|
||||
edits code directly in Phase 2, so jsonl curation is skipped —
|
||||
the inline workflow loads `trellis-before-dev` instead of injecting JSONL
|
||||
into a sub-agent. -->
|
||||
|
||||
[workflow-state:planning-inline]
|
||||
Load `trellis-brainstorm`; stay in planning.
|
||||
Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`.
|
||||
Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position.
|
||||
Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`.
|
||||
[/workflow-state:planning-inline]
|
||||
|
||||
### Phase 2: Execute
|
||||
- 2.1 Implement `[required · repeatable]`
|
||||
- 2.2 Quality check `[required · repeatable]`
|
||||
- 2.3 Rollback `[on demand]`
|
||||
|
||||
<!-- Per-turn breadcrumb: shown while status='in_progress'.
|
||||
Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from
|
||||
task.py start until task.py archive; only archive flips it). The body
|
||||
therefore must cover every required step from implementation through
|
||||
commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
|
||||
|
||||
Sub-agent dispatch protocol applies to all platforms and all sub-agents, including class-2 Codex/Gemini/Qoder/Copilot/ZCode/Reasonix/Trae and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions.
|
||||
|
||||
[workflow-state:in_progress]
|
||||
Tools: `trellis-implement` / `trellis-research` are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent form when verifying after code changes.
|
||||
Flow: `trellis-implement` -> `trellis-check` -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
|
||||
Main-session default: dispatch implement/check sub-agents. Sub-agent self-exemption: if already running as `trellis-implement`, do NOT spawn another `trellis-implement` or `trellis-check`; if already running as `trellis-check`, do NOT spawn another `trellis-check` or `trellis-implement`. Dispatch is main session only.
|
||||
Dispatch prompt starts with `Active task: <task path from task.py current>`. Read context: jsonl entries -> `prd.md` -> `design.md if present` -> `implement.md if present`.
|
||||
[/workflow-state:in_progress]
|
||||
|
||||
<!-- Per-turn breadcrumb: shown while status='in_progress' when
|
||||
codex.dispatch_mode=inline. Codex-only opt-in alternate to
|
||||
[workflow-state:in_progress]. The main session edits code directly
|
||||
instead of dispatching sub-agents. -->
|
||||
|
||||
[workflow-state:in_progress-inline]
|
||||
Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
|
||||
Do not dispatch implement/check sub-agents in inline mode.
|
||||
Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills.
|
||||
[/workflow-state:in_progress-inline]
|
||||
|
||||
### Phase 3: Finish
|
||||
- 3.2 Debug retrospective `[on demand]`
|
||||
- 3.3 Spec update `[required · once]`
|
||||
- 3.4 Commit changes `[required · once]`
|
||||
- 3.5 Wrap-up reminder
|
||||
|
||||
> Note: step 3.1 was folded into 2.2 (last-iteration full-scope check) and 3.4 (commit preamble). Numbering kept stable to avoid breaking external references.
|
||||
|
||||
<!-- Per-turn breadcrumb: shown while status='completed'.
|
||||
Currently DEAD in normal flow: cmd_archive writes status='completed' in
|
||||
the same call that moves the task dir to archive/, so the active-task
|
||||
resolver loses the pointer and the hook never fires on archived tasks.
|
||||
Block preserved for a future status-transition redesign (e.g. an
|
||||
explicit in_progress→completed command). Edit through the same spec
|
||||
channel as the live blocks. -->
|
||||
|
||||
[workflow-state:completed]
|
||||
Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first.
|
||||
[/workflow-state:completed]
|
||||
|
||||
### Rules
|
||||
|
||||
1. Identify which Phase you're in, then continue from the next step there
|
||||
2. Run steps in order inside each Phase; `[required]` steps can't be skipped
|
||||
3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute)
|
||||
4. Steps tagged `[once]` are skipped if the output already exists; don't re-run
|
||||
5. Artifact presence informs the next step; missing `design.md` / `implement.md` is valid for lightweight tasks and incomplete planning for complex tasks.
|
||||
|
||||
### Active Task Routing
|
||||
|
||||
When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.
|
||||
|
||||
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
- Planning or unclear requirements -> `trellis-brainstorm`.
|
||||
- `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
|
||||
- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
- Planning or unclear requirements -> `trellis-brainstorm`.
|
||||
- Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
|
||||
- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
### Guardrails
|
||||
|
||||
- Task creation approval is not implementation approval; implementation waits for `task.py start` after artifact review.
|
||||
- PRD-only is valid for lightweight tasks; complex tasks need `design.md` + `implement.md`.
|
||||
- Planning must be persisted to task artifacts; checks must run before reporting completion.
|
||||
|
||||
### Loading Step Detail
|
||||
|
||||
At each step, run this to fetch detailed guidance:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
|
||||
# e.g. python3 ./.trellis/scripts/get_context.py --mode phase --step 1.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Plan
|
||||
|
||||
Goal: classify the request, get task-creation consent when a task is needed, and produce the planning artifacts required before implementation.
|
||||
|
||||
#### 1.0 Create task `[required · once]`
|
||||
|
||||
Create the task directory only after task-creation consent. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<task title>" --slug <name>
|
||||
```
|
||||
|
||||
`--slug` is the human-readable name only. Do **not** include the `MM-DD-` date prefix; `task.py create` adds that prefix automatically.
|
||||
|
||||
For task trees, create the parent task first and then create each child with `--parent <parent-dir>`. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable.
|
||||
|
||||
After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow-state:planning]`, telling the AI to stay in planning.
|
||||
|
||||
Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4.
|
||||
|
||||
Skip when `python3 ./.trellis/scripts/task.py current --source` already points to a task.
|
||||
|
||||
#### 1.1 Requirement exploration `[required · repeatable]`
|
||||
|
||||
Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance.
|
||||
|
||||
The brainstorm skill will guide you to:
|
||||
- Ask one question at a time
|
||||
- Prefer researching over asking the user
|
||||
- Prefer offering options over open-ended questions
|
||||
- Update `prd.md` immediately after each user answer
|
||||
- Split large scopes into a parent task plus child tasks when the deliverables can be verified independently
|
||||
- Keep `prd.md` focused on requirements and acceptance criteria
|
||||
- For complex tasks, produce `design.md` and `implement.md` before implementation starts
|
||||
|
||||
When considering a parent/child split:
|
||||
- Use a parent task when one request contains several independently verifiable deliverables.
|
||||
- Parent tasks own source requirements, child-task mapping, cross-child acceptance criteria, and final integration review.
|
||||
- Child tasks own actual deliverables that can be planned, implemented, checked, and archived independently.
|
||||
- Parent/child structure is not a dependency system. If child B depends on child A, write that ordering in child B's `prd.md` / `implement.md`.
|
||||
- Start the child task that owns the next deliverable. Do not start the parent unless the parent itself has direct implementation work.
|
||||
|
||||
Return to this step whenever requirements change and revise the relevant artifact.
|
||||
|
||||
#### 1.2 Research `[optional · repeatable]`
|
||||
|
||||
Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
|
||||
|
||||
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
Spawn the research sub-agent:
|
||||
|
||||
- **Agent type**: `trellis-research`
|
||||
- **Task description**: Research <specific question>
|
||||
- **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. (For `codex-inline` this avoids the `fork_turns="none"` isolation that prevents `trellis-research` sub-agents from resolving the active task path.)
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
**Research artifact conventions**:
|
||||
- One file per research topic (e.g. `research/auth-library-comparison.md`)
|
||||
- Record third-party library usage examples, API references, version constraints in files
|
||||
- Note relevant spec file paths you discovered for later reference
|
||||
|
||||
Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user.
|
||||
|
||||
**Key principle**: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't.
|
||||
|
||||
#### 1.3 Configure context `[required · once]`
|
||||
|
||||
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
|
||||
|
||||
**Location**: `{TASK_DIR}/implement.jsonl` and `{TASK_DIR}/check.jsonl` (already exist).
|
||||
|
||||
**Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative.
|
||||
|
||||
**What to put in**:
|
||||
- **Spec files** — `.trellis/spec/<package>/<layer>/index.md` and any specific guideline files (`error-handling.md`, `conventions.md`, etc.) relevant to this task
|
||||
- **Research files** — `{TASK_DIR}/research/*.md` that the sub-agent will need to consult
|
||||
|
||||
**What NOT to put in**:
|
||||
- Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here
|
||||
- Files you're about to modify — same reason
|
||||
|
||||
**Split between the two files**:
|
||||
- `implement.jsonl` → specs + research the implement sub-agent needs to write code correctly
|
||||
- `check.jsonl` → specs for the check sub-agent (quality guidelines, check conventions, same research if needed)
|
||||
|
||||
These manifests do not replace `implement.md`. `implement.md` is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load.
|
||||
|
||||
**How to discover relevant specs**:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
Lists every package + its spec layers with paths. Pick the entries that match this task's domain.
|
||||
|
||||
**How to append entries**:
|
||||
|
||||
Either edit the jsonl file directly in your editor, or use:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
|
||||
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
|
||||
```
|
||||
|
||||
Delete the seed `_example` line once real entries exist (optional — it's skipped automatically by consumers).
|
||||
|
||||
Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one real `{"file": "...", "reason": "..."}` entry before `task.py start`. The seed `_example` row alone is not ready.
|
||||
|
||||
Skip this step only when both files already have real curated entries.
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
#### 1.4 Activate task `[required · once]`
|
||||
|
||||
After artifact review, flip the task status to `in_progress`:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py start <task-dir>
|
||||
```
|
||||
|
||||
For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state.
|
||||
|
||||
After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows.
|
||||
|
||||
If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry.
|
||||
|
||||
#### 1.5 Completion criteria
|
||||
|
||||
| Condition | Required |
|
||||
|------|:---:|
|
||||
| `prd.md` exists | ✅ |
|
||||
| User confirms task should enter implementation | ✅ |
|
||||
| `task.py start` has been run (status = in_progress) | ✅ |
|
||||
| `research/` has artifacts (complex tasks) | recommended |
|
||||
| `design.md` exists (complex tasks) | ✅ |
|
||||
| `implement.md` exists (complex tasks) | ✅ |
|
||||
|
||||
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
| `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Execute
|
||||
|
||||
Goal: turn reviewed planning artifacts into code that passes quality checks.
|
||||
|
||||
#### 2.1 Implement `[required · repeatable]`
|
||||
|
||||
[Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi]
|
||||
|
||||
Spawn the implement sub-agent:
|
||||
|
||||
- **Agent type**: `trellis-implement`
|
||||
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
|
||||
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
|
||||
|
||||
The platform hook/plugin auto-handles:
|
||||
- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
|
||||
- Injects `prd.md`, `design.md` if present, and `implement.md` if present
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi]
|
||||
|
||||
[codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]
|
||||
|
||||
Spawn the implement sub-agent:
|
||||
|
||||
- **Agent type**: `trellis-implement`
|
||||
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
|
||||
- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`.
|
||||
|
||||
The pull-based sub-agent definition auto-handles the context load requirement:
|
||||
- Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present
|
||||
- Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding
|
||||
|
||||
[/codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]
|
||||
|
||||
[Kiro]
|
||||
|
||||
Spawn the implement sub-agent:
|
||||
|
||||
- **Agent type**: `trellis-implement`
|
||||
- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
|
||||
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
|
||||
|
||||
The platform prelude auto-handles the context load requirement:
|
||||
- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
|
||||
- Injects `prd.md`, `design.md` if present, and `implement.md` if present
|
||||
|
||||
[/Kiro]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
1. Load the `trellis-before-dev` skill to read project guidelines
|
||||
2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present
|
||||
3. Consult materials under `{TASK_DIR}/research/`
|
||||
4. Implement the code per reviewed artifacts
|
||||
5. Run project lint and type-check
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
#### 2.2 Quality check `[required · repeatable]`
|
||||
|
||||
[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
Spawn the check sub-agent:
|
||||
|
||||
- **Agent type**: `trellis-check`
|
||||
- **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
|
||||
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
|
||||
|
||||
The check agent's job:
|
||||
- Review code changes against specs
|
||||
- Review code changes against `prd.md`, `design.md` if present, and `implement.md` if present
|
||||
- Auto-fix issues it finds
|
||||
- Run lint and typecheck to verify
|
||||
|
||||
[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae]
|
||||
|
||||
[codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
Load the `trellis-check` skill and verify the code per its guidance:
|
||||
- Spec compliance
|
||||
- lint / type-check / tests
|
||||
- Cross-layer consistency (when changes span layers)
|
||||
|
||||
If issues are found → fix → re-check, until green.
|
||||
|
||||
[/codex-inline, Kilo, Antigravity, Devin]
|
||||
|
||||
**Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.
|
||||
|
||||
#### 2.3 Rollback `[on demand]`
|
||||
|
||||
- `check` reveals a prd defect → return to Phase 1, fix `prd.md`, then redo 2.1
|
||||
- Implementation went wrong → revert code, redo 2.1
|
||||
- Need more research → research (same as Phase 1.2), write findings into `research/`
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Finish
|
||||
|
||||
Goal: ensure code quality, capture lessons, record the work.
|
||||
|
||||
#### 3.2 Debug retrospective `[on demand]`
|
||||
|
||||
If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to:
|
||||
- Classify the root cause
|
||||
- Explain why earlier fixes failed
|
||||
- Propose prevention
|
||||
|
||||
The goal is to capture debugging lessons so the same class of issue doesn't recur.
|
||||
|
||||
#### 3.3 Spec update `[required · once]`
|
||||
|
||||
Load the `trellis-update-spec` skill and review whether this task produced new knowledge worth recording:
|
||||
- Newly discovered patterns or conventions
|
||||
- Pitfalls you hit
|
||||
- New technical decisions
|
||||
|
||||
Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
|
||||
|
||||
#### 3.4 Commit changes `[required · once]`
|
||||
|
||||
**Spec-sync preamble**: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in `.trellis/spec/` so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up.
|
||||
|
||||
The AI drives a batched commit of this task's code changes so `/finish-work` can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved.
|
||||
|
||||
**Step-by-step**:
|
||||
|
||||
1. **Inspect dirty state**:
|
||||
```bash
|
||||
git status --porcelain
|
||||
```
|
||||
Snapshot every dirty path. If the working tree is clean, skip to 3.5.
|
||||
|
||||
2. **Learn commit style** from recent history (so drafted messages blend in):
|
||||
```bash
|
||||
git log --oneline -5
|
||||
```
|
||||
Note the prefix convention (`feat:` / `fix:` / `chore:` / `docs:` ...), language (中文/English), and length style.
|
||||
|
||||
3. **Classify dirty files into two groups**:
|
||||
- **AI-edited this session** — files you wrote/edited via Edit/Write/Bash tool calls in this session. You know what changed and why.
|
||||
- **Unrecognized** — dirty files you did NOT touch this session (could be the user's manual edits, leftover WIP from a previous session, or unrelated work). Do NOT silently include these.
|
||||
|
||||
4. **Draft a commit plan**. Group AI-edited files into logical commits (1 commit per coherent change unit, not 1 commit per file). Each entry: `<commit message>` + file list. List unrecognized files separately at the bottom.
|
||||
|
||||
5. **Present the plan once, ask for one-shot confirmation**. Format:
|
||||
```
|
||||
Proposed commits (in order):
|
||||
1. <message>
|
||||
- <file>
|
||||
- <file>
|
||||
2. <message>
|
||||
- <file>
|
||||
|
||||
Unrecognized dirty files (NOT in any commit — confirm include/exclude):
|
||||
- <file>
|
||||
- <file>
|
||||
|
||||
Reply 'ok' / '行' to execute. Reply with edits, or '我自己来' / 'manual' to abort.
|
||||
```
|
||||
|
||||
6. **On confirmation**: run `git add <files>` + `git commit -m "<msg>"` for each batch in order. Do not amend. Do not push.
|
||||
|
||||
7. **On rejection** (user replies "不行" / "我自己来" / "manual" / any pushback on the plan): stop. Do not attempt a second plan. The user will commit by hand; you skip ahead to 3.5 once they confirm.
|
||||
|
||||
**Rules**:
|
||||
- No `git commit --amend` anywhere — three-stage three-commit flow (work commits → archive commit → journal commit).
|
||||
- Never push to remote in this step.
|
||||
- If the user wants different message wording but accepts the file grouping, edit the message and re-confirm once — but if they reject the grouping, exit to manual mode.
|
||||
- The batched plan is one prompt; do not prompt per commit.
|
||||
|
||||
#### 3.5 Wrap-up reminder
|
||||
|
||||
After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session).
|
||||
|
||||
---
|
||||
|
||||
## Customizing Trellis (for forks)
|
||||
|
||||
This section is for developers who want to modify the Trellis workflow itself. All customization is done by editing this file; the scripts are parsers only.
|
||||
|
||||
### Changing what a step means
|
||||
|
||||
Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants:
|
||||
- No active task must triage first and ask for task-creation consent before creating a Trellis task.
|
||||
- Planning must distinguish lightweight PRD-only tasks from complex tasks that require `prd.md`, `design.md`, and `implement.md` before start.
|
||||
- Every required execution path must keep the Phase 3.4 commit reminder reachable before `/trellis:finish-work`.
|
||||
|
||||
All tag blocks live in the `## Phase Index` section above, immediately after each phase summary:
|
||||
|
||||
| Scope | Corresponding tag |
|
||||
|---|---|
|
||||
| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
|
||||
| All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
|
||||
| Codex inline Phase 1 | `[workflow-state:planning-inline]` |
|
||||
| Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
|
||||
| Codex inline Phase 2 + Phase 3.2–3.4 | `[workflow-state:in_progress-inline]` |
|
||||
| After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) |
|
||||
|
||||
### Changing the per-turn prompt text
|
||||
|
||||
Directly edit the body of the corresponding `[workflow-state:STATUS]` block. After editing, run `trellis update` (if you're a template maintainer) or restart your AI session (if you're customizing your own project) — no script changes required.
|
||||
|
||||
### Adding a custom status
|
||||
|
||||
Add a new block:
|
||||
|
||||
```
|
||||
[workflow-state:my-status]
|
||||
your per-turn prompt text
|
||||
[/workflow-state:my-status]
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- STATUS charset: `[A-Za-z0-9_-]+` (underscores and hyphens allowed, e.g. `in-review`, `blocked-by-team`)
|
||||
- A lifecycle hook must write `task.json.status` to your custom value, otherwise the tag is never read
|
||||
- Lifecycle hooks live in `task.json.hooks.after_*` and bind to one of `after_create / after_start / after_finish / after_archive`
|
||||
|
||||
### Adding a lifecycle hook
|
||||
|
||||
Add a `hooks` field to your `task.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"after_finish": [
|
||||
"your-script-or-command-here"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Supported events: `after_create / after_start / after_finish / after_archive`. Note that `after_finish` ≠ a status change (it only clears the active-task pointer); use `after_archive` for "task is done" notifications.
|
||||
|
||||
### Full contract
|
||||
|
||||
For the workflow state machine's runtime contract, the locations of all status writers, pseudo-statuses (`no_task` / `stale_<source_type>`), the hook reachability matrix, and other deep details, see:
|
||||
|
||||
- `.trellis/spec/cli/backend/workflow-state-contract.md` — runtime contract + writer table + test invariants
|
||||
- `.trellis/scripts/inject-workflow-state.py` — actual parser (reads workflow.md only, no embedded text)
|
||||
Vendored
+8
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"recommendations": [
|
||||
"Vue.volar",
|
||||
"dbaeumer.vscode-eslint",
|
||||
"esbenp.prettier-vscode",
|
||||
"bradlc.vscode-tailwindcss"
|
||||
]
|
||||
}
|
||||
Vendored
+33
@@ -0,0 +1,33 @@
|
||||
{
|
||||
"[vue]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": "explicit"
|
||||
}
|
||||
},
|
||||
"[typescript]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": "explicit"
|
||||
}
|
||||
},
|
||||
"[javascript]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true
|
||||
},
|
||||
"[json]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true
|
||||
},
|
||||
"[css]": {
|
||||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||||
"editor.formatOnSave": true
|
||||
},
|
||||
"eslint.workingDirectories": ["."],
|
||||
"eslint.validate": ["javascript", "typescript", "vue"],
|
||||
"files.exclude": {
|
||||
"**/.DS_Store": true
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
# AGENTS.md
|
||||
|
||||
oci-portal-dash：OCI Portal 前端（Vue 3 + Vite + TypeScript + Naive UI + Tailwind CSS v4 + Pinia）。本文件面向 AI 编码助手；人类文档见 [README.md](README.md)。
|
||||
|
||||
## 语言与交付
|
||||
|
||||
- 用中文回答与写注释
|
||||
- commit message 用中文，不超过 50 字
|
||||
- 函数不超过 30 行
|
||||
|
||||
## 仓库操作铁律
|
||||
|
||||
- **仅当用户明确提出「提交」「推送」时才执行 git 操作**
|
||||
- 双 remote：`gitea`（日常默认）与 `github`（公共镜像）；推送默认到 `gitea`，仅用户明示「发版」或「推到 github」时才推 `github`
|
||||
|
||||
## 编码规范（写代码前读）
|
||||
|
||||
- 规范入口：[.trellis/spec/frontend/index.md](.trellis/spec/frontend/index.md)（目录结构 / TS 与组件写法 / 设计 token / API 与状态分篇）
|
||||
- 颜色、圆角、间距用设计 token，禁止硬编码 hex（组件库必需的具体值除外）
|
||||
- 新增请求走 `src/api/` 统一封装，DTO 类型进 `src/types/`
|
||||
- 文件放对层：views / components / composables / api / stores / types
|
||||
|
||||
## 质量门（提交前必过）
|
||||
|
||||
```bash
|
||||
npm run lint && npm run typecheck && npm run build
|
||||
```
|
||||
|
||||
## 文档同步
|
||||
|
||||
- 改页面能力 / 环境变量 / 构建形态时，同步更新 README.md；CHANGELOG.md 只在发版时写对应版本段，日常提交不记录
|
||||
|
||||
|
||||
<!-- TRELLIS:START -->
|
||||
# Trellis Instructions
|
||||
|
||||
These instructions are for AI assistants working in this project.
|
||||
|
||||
This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:
|
||||
|
||||
- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
|
||||
- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
|
||||
- `.trellis/workspace/` — per-developer journals and session traces
|
||||
- `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)
|
||||
|
||||
If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
|
||||
|
||||
If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
|
||||
- `.agents/skills/` — reusable Trellis skills
|
||||
- `.codex/agents/` — optional custom subagents
|
||||
|
||||
Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
|
||||
|
||||
<!-- TRELLIS:END -->
|
||||
@@ -0,0 +1,13 @@
|
||||
# Changelog
|
||||
|
||||
格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。
|
||||
|
||||
## [0.0.1] - 2026-07-09
|
||||
|
||||
首个版本：OCI Portal 前端。
|
||||
|
||||
### Added
|
||||
|
||||
- 全套页面
|
||||
- 网页串行控制台（xterm.js）与 VNC 控制台（noVNC）
|
||||
- Anthropic 风设计 token 体系（Naive UI + Tailwind v4），明暗双主题
|
||||
@@ -0,0 +1,54 @@
|
||||
# AGENTS.md
|
||||
|
||||
oci-portal-dash：OCI Portal 前端（Vue 3 + Vite + TypeScript + Naive UI + Tailwind CSS v4 + Pinia）。本文件面向 AI 编码助手；人类文档见 [README.md](README.md)。
|
||||
|
||||
## 语言与交付
|
||||
|
||||
- 用中文回答与写注释
|
||||
- commit message 用中文，不超过 50 字
|
||||
- 函数不超过 30 行
|
||||
|
||||
## 仓库操作铁律
|
||||
|
||||
- **仅当用户明确提出「提交」「推送」时才执行 git 操作**
|
||||
- 双 remote：`gitea`（日常默认）与 `github`（公共镜像）；推送默认到 `gitea`，仅用户明示「发版」或「推到 github」时才推 `github`
|
||||
|
||||
## 编码规范（写代码前读）
|
||||
|
||||
- 规范入口：[.trellis/spec/frontend/index.md](.trellis/spec/frontend/index.md)（目录结构 / TS 与组件写法 / 设计 token / API 与状态分篇）
|
||||
- 颜色、圆角、间距用设计 token，禁止硬编码 hex（组件库必需的具体值除外）
|
||||
- 新增请求走 `src/api/` 统一封装，DTO 类型进 `src/types/`
|
||||
- 文件放对层：views / components / composables / api / stores / types
|
||||
|
||||
## 质量门（提交前必过）
|
||||
|
||||
```bash
|
||||
npm run lint && npm run typecheck && npm run build
|
||||
```
|
||||
|
||||
## 文档同步
|
||||
|
||||
- 改页面能力 / 环境变量 / 构建形态时，同步更新 README.md；CHANGELOG.md 只在发版时写对应版本段，日常提交不记录
|
||||
|
||||
|
||||
<!-- TRELLIS:START -->
|
||||
# Trellis Instructions
|
||||
|
||||
These instructions are for AI assistants working in this project.
|
||||
|
||||
This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:
|
||||
|
||||
- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
|
||||
- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
|
||||
- `.trellis/workspace/` — per-developer journals and session traces
|
||||
- `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)
|
||||
|
||||
If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.
|
||||
|
||||
If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
|
||||
- `.agents/skills/` — reusable Trellis skills
|
||||
- `.codex/agents/` — optional custom subagents
|
||||
|
||||
Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
|
||||
|
||||
<!-- TRELLIS:END -->
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Wang Defa
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,37 @@
|
||||
# OCI Portal Dash
|
||||
|
||||
[OCI Portal](https://github.com/wangdefaa/oci-portal) 的前端工程：Vue 3 + Vite + TypeScript + Naive UI + Tailwind CSS v4 + ECharts + Pinia。
|
||||
|
||||
## 开发
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev # http://localhost:5173,默认 mock 模式开箱可视
|
||||
```
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `VITE_MOCK` | dev 为 `1` | `1` 走内置 mock 数据不依赖后端；置 `0` 走真实请求（dev server 将 `/api`、`/ai/` 代理到 `http://localhost:8080`，需先启动后端） |
|
||||
|
||||
## 质量检查与构建
|
||||
|
||||
```bash
|
||||
npm run lint # ESLint + Prettier(带 --fix)
|
||||
npm run typecheck # vue-tsc --noEmit
|
||||
npm run build # 类型检查 + 产物构建到 dist/
|
||||
```
|
||||
|
||||
## 部署
|
||||
|
||||
两种形态：
|
||||
|
||||
1. **静态直出**：`dist/` 交给 Caddy/nginx 伺服，`/api/*`、`/ai/*` 反代到后端
|
||||
2. **单文件嵌入**：产物经后端 `go:embed` 打进单个二进制。本仓库 Release 流程（tag `v*`）自动构建并发布 `dist.zip`，后端 Release 流程从这里下载嵌入；本地则 `npm run build` 后把 `dist/` 内容拷入后端 `internal/webui/dist/`
|
||||
|
||||
## 规范
|
||||
|
||||
编码规范与项目约定见 [AGENTS.md](AGENTS.md) 与 [.trellis/spec/](.trellis/spec/)。
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE)
|
||||
Generated
+14
-49
@@ -11,11 +11,11 @@
|
||||
"@novnc/novnc": "^1.7.0",
|
||||
"@xterm/addon-fit": "^0.11.0",
|
||||
"@xterm/xterm": "^6.0.0",
|
||||
"echarts": "^5.6.0",
|
||||
"echarts": "^6.1.0",
|
||||
"naive-ui": "^2.41.0",
|
||||
"pinia": "^2.3.0",
|
||||
"vue": "^3.5.13",
|
||||
"vue-echarts": "^7.0.3",
|
||||
"vue-echarts": "^8.0.1",
|
||||
"vue-router": "^4.5.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
@@ -2461,13 +2461,13 @@
|
||||
}
|
||||
},
|
||||
"node_modules/echarts": {
|
||||
"version": "5.6.0",
|
||||
"resolved": "https://registry.npmjs.org/echarts/-/echarts-5.6.0.tgz",
|
||||
"integrity": "sha512-oTbVTsXfKuEhxftHqL5xprgLoc0k7uScAwtryCgWF6hPYFLRwOUHiFmHGCBKP5NPFNkDVopOieyUqYGH8Fa3kA==",
|
||||
"version": "6.1.0",
|
||||
"resolved": "https://registry.npmjs.org/echarts/-/echarts-6.1.0.tgz",
|
||||
"integrity": "sha512-q0yaFPggC9FUdsWH4blavRWFmxdrIodbkoKNAjJudAI6CA9gNPxHtV2RcZNEepZVlk4yvBYkOkbk6HIVpIyHZA==",
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {
|
||||
"tslib": "2.3.0",
|
||||
"zrender": "5.6.1"
|
||||
"zrender": "6.1.0"
|
||||
}
|
||||
},
|
||||
"node_modules/enhanced-resolve": {
|
||||
@@ -4531,48 +4531,13 @@
|
||||
}
|
||||
},
|
||||
"node_modules/vue-echarts": {
|
||||
"version": "7.0.3",
|
||||
"resolved": "https://registry.npmjs.org/vue-echarts/-/vue-echarts-7.0.3.tgz",
|
||||
"integrity": "sha512-/jSxNwOsw5+dYAUcwSfkLwKPuzTQ0Cepz1LxCOpj2QcHrrmUa/Ql0eQqMmc1rTPQVrh2JQ29n2dhq75ZcHvRDw==",
|
||||
"version": "8.0.1",
|
||||
"resolved": "https://registry.npmjs.org/vue-echarts/-/vue-echarts-8.0.1.tgz",
|
||||
"integrity": "sha512-23rJTFLu1OUEGRWjJGmdGt8fP+8+ja1gVgzMYPIPaHWpXegcO1viIAaeu2H4QHESlVeHzUAHIxKXGrwjsyXAaA==",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"vue-demi": "^0.13.11"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@vue/runtime-core": "^3.0.0",
|
||||
"echarts": "^5.5.1",
|
||||
"vue": "^2.7.0 || ^3.1.1"
|
||||
},
|
||||
"peerDependenciesMeta": {
|
||||
"@vue/runtime-core": {
|
||||
"optional": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"node_modules/vue-echarts/node_modules/vue-demi": {
|
||||
"version": "0.13.11",
|
||||
"resolved": "https://registry.npmjs.org/vue-demi/-/vue-demi-0.13.11.tgz",
|
||||
"integrity": "sha512-IR8HoEEGM65YY3ZJYAjMlKygDQn25D5ajNFNoKh9RSDMQtlzCxtfQjdQgv9jjK+m3377SsJXY8ysq8kLCZL25A==",
|
||||
"hasInstallScript": true,
|
||||
"license": "MIT",
|
||||
"bin": {
|
||||
"vue-demi-fix": "bin/vue-demi-fix.js",
|
||||
"vue-demi-switch": "bin/vue-demi-switch.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=12"
|
||||
},
|
||||
"funding": {
|
||||
"url": "https://github.com/sponsors/antfu"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"@vue/composition-api": "^1.0.0-rc.1",
|
||||
"vue": "^3.0.0-0 || ^2.6.0"
|
||||
},
|
||||
"peerDependenciesMeta": {
|
||||
"@vue/composition-api": {
|
||||
"optional": true
|
||||
}
|
||||
"echarts": "^6.0.0",
|
||||
"vue": "^3.3.0"
|
||||
}
|
||||
},
|
||||
"node_modules/vue-eslint-parser": {
|
||||
@@ -4712,9 +4677,9 @@
|
||||
}
|
||||
},
|
||||
"node_modules/zrender": {
|
||||
"version": "5.6.1",
|
||||
"resolved": "https://registry.npmjs.org/zrender/-/zrender-5.6.1.tgz",
|
||||
"integrity": "sha512-OFXkDJKcrlx5su2XbzJvj/34Q3m6PvyCZkVPHGYpcCJ52ek4U/ymZyfuV1nKE23AyBJ51E/6Yr0mhZ7xGTO4ag==",
|
||||
"version": "6.1.0",
|
||||
"resolved": "https://registry.npmjs.org/zrender/-/zrender-6.1.0.tgz",
|
||||
"integrity": "sha512-oEGMDB6pOP2S6OwRR4PdVv610zrjnA3Bh+JnSG12fYJlBKjtNAoEb5fSUoCOOINlH96I2fU38/A2UpRKs67xYQ==",
|
||||
"license": "BSD-3-Clause",
|
||||
"dependencies": {
|
||||
"tslib": "2.3.0"
|
||||
|
||||
+2
-2
@@ -15,11 +15,11 @@
|
||||
"@novnc/novnc": "^1.7.0",
|
||||
"@xterm/addon-fit": "^0.11.0",
|
||||
"@xterm/xterm": "^6.0.0",
|
||||
"echarts": "^5.6.0",
|
||||
"echarts": "^6.1.0",
|
||||
"naive-ui": "^2.41.0",
|
||||
"pinia": "^2.3.0",
|
||||
"vue": "^3.5.13",
|
||||
"vue-echarts": "^7.0.3",
|
||||
"vue-echarts": "^8.0.1",
|
||||
"vue-router": "^4.5.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
||||
+18
-18
@@ -104,9 +104,9 @@ export const mockProxies = [
|
||||
export const mockConfigs: OciConfig[] = [
|
||||
cfg({
|
||||
id: 1,
|
||||
alias: 'BCDE主号',
|
||||
alias: 'XXXX主号',
|
||||
group: '生产',
|
||||
tenancyName: 'bcdemain',
|
||||
tenancyName: 'XXXXmain',
|
||||
accountType: 'paid',
|
||||
paymentModel: 'PAYG',
|
||||
subscriptionTier: 'FREE_AND_PAID',
|
||||
@@ -367,7 +367,7 @@ export const mockTasks: Task[] = [
|
||||
},
|
||||
{
|
||||
id: 5,
|
||||
name: 'BCDE 每小时测活',
|
||||
name: 'XXXX 每小时测活',
|
||||
type: 'health_check',
|
||||
cronExpr: '7 * * * *',
|
||||
payload: '{"ociConfigIds":[1,2,3,4]}',
|
||||
@@ -620,7 +620,7 @@ export const mockUsers: IamUser[] = [
|
||||
id: 'ocid1.user..apiadmin',
|
||||
name: 'api-admin',
|
||||
description: '当前 API Key 签名用户',
|
||||
email: 'admin@bcde.io',
|
||||
email: 'admin@XXXX.io',
|
||||
emailVerified: true,
|
||||
mfaActivated: true,
|
||||
lifecycleState: 'ACTIVE',
|
||||
@@ -632,7 +632,7 @@ export const mockUsers: IamUser[] = [
|
||||
id: 'ocid1.user..consoleadmin',
|
||||
name: 'console-admin',
|
||||
description: '控制台管理员',
|
||||
email: 'console-admin@bcde.io',
|
||||
email: 'console-admin@XXXX.io',
|
||||
emailVerified: true,
|
||||
mfaActivated: true,
|
||||
lifecycleState: 'ACTIVE',
|
||||
@@ -644,7 +644,7 @@ export const mockUsers: IamUser[] = [
|
||||
id: 'ocid1.user..devzhang',
|
||||
name: 'dev-zhang',
|
||||
description: '开发',
|
||||
email: 'zhang@bcde.io',
|
||||
email: 'zhang@XXXX.io',
|
||||
emailVerified: false,
|
||||
mfaActivated: false,
|
||||
lifecycleState: 'ACTIVE',
|
||||
@@ -654,7 +654,7 @@ export const mockUsers: IamUser[] = [
|
||||
},
|
||||
{
|
||||
id: 'ocid1.user..fedwang',
|
||||
name: 'bcde_fed/wang.defa',
|
||||
name: 'XXXX_fed/wang.defa',
|
||||
description: '联邦用户 · Keycloak',
|
||||
email: '',
|
||||
emailVerified: false,
|
||||
@@ -700,7 +700,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: 'TerminateInstance',
|
||||
source: 'ComputeApi',
|
||||
resourceName: 'web-1',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: 'api-admin',
|
||||
ipAddress: '203.0.113.10',
|
||||
status: '204',
|
||||
@@ -712,7 +712,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: 'LaunchInstance',
|
||||
source: 'ComputeApi',
|
||||
resourceName: 'arm-snatch-1',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: 'api-admin',
|
||||
ipAddress: '203.0.113.10',
|
||||
status: '500',
|
||||
@@ -736,7 +736,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: 'GetUser',
|
||||
source: 'IdentityControlPlane',
|
||||
resourceName: 'dev-zhang',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: 'dev-zhang',
|
||||
ipAddress: '198.51.100.24',
|
||||
status: '404',
|
||||
@@ -760,7 +760,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: 'ListEvents',
|
||||
source: 'Audit',
|
||||
resourceName: '',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: 'console-admin',
|
||||
ipAddress: '198.51.100.7',
|
||||
status: '200',
|
||||
@@ -772,7 +772,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: 'CreateSwiftPassword',
|
||||
source: 'IdentityControlPlane',
|
||||
resourceName: 'dev-zhang',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: 'dev-zhang',
|
||||
ipAddress: '198.51.100.24',
|
||||
status: '401',
|
||||
@@ -785,7 +785,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
source: 'VcnApi',
|
||||
resourceName: 'Default Security List',
|
||||
compartmentName: 'network',
|
||||
principalName: 'bcde_fed/wang.defa',
|
||||
principalName: 'XXXX_fed/wang.defa',
|
||||
ipAddress: '192.0.2.88',
|
||||
status: '200',
|
||||
requestAction: 'PUT',
|
||||
@@ -796,7 +796,7 @@ const mockAuditEventsBase: Omit<AuditEvent, 'eventId'>[] = [
|
||||
eventName: '',
|
||||
source: 'CloudGuardResponderEngine',
|
||||
resourceName: '',
|
||||
compartmentName: 'bcde (root)',
|
||||
compartmentName: 'XXXX (root)',
|
||||
principalName: '',
|
||||
ipAddress: '',
|
||||
status: '',
|
||||
@@ -813,7 +813,7 @@ export const mockAuditEvents: AuditEvent[] = mockAuditEventsBase.map((e, i) => (
|
||||
export const mockIdps: IdentityProvider[] = [
|
||||
{
|
||||
id: '54a0260f7a75',
|
||||
name: 'BCDE-keycloak',
|
||||
name: 'XXXX-keycloak',
|
||||
type: 'SAML',
|
||||
enabled: true,
|
||||
partnerProviderId: 'https://auth.example.test/realms/oci',
|
||||
@@ -881,7 +881,7 @@ export const mockPolicies: PasswordPolicy[] = [
|
||||
]
|
||||
|
||||
export const mockRecipients: NotificationRecipients = {
|
||||
recipients: ['admin@bcde.io', 'ops@bcde.io'],
|
||||
recipients: ['admin@XXXX.io', 'ops@XXXX.io'],
|
||||
testModeEnabled: true,
|
||||
}
|
||||
|
||||
@@ -1256,7 +1256,7 @@ export const mockCompartments: Record<number, Compartment[]> = {
|
||||
id: 'ocid1.compartment.oc1..dev',
|
||||
name: 'dev',
|
||||
description: '开发环境资源',
|
||||
parentId: 'ocid1.tenancy.oc1..BCDE主号xxxx',
|
||||
parentId: 'ocid1.tenancy.oc1..XXXX主号xxxx',
|
||||
lifecycleState: 'ACTIVE',
|
||||
timeCreated: '2026-05-20T00:00:00Z',
|
||||
},
|
||||
@@ -1264,7 +1264,7 @@ export const mockCompartments: Record<number, Compartment[]> = {
|
||||
id: 'ocid1.compartment.oc1..prodnet',
|
||||
name: 'prod-network',
|
||||
description: '生产网络资源',
|
||||
parentId: 'ocid1.tenancy.oc1..BCDE主号xxxx',
|
||||
parentId: 'ocid1.tenancy.oc1..XXXX主号xxxx',
|
||||
lifecycleState: 'ACTIVE',
|
||||
timeCreated: '2026-06-01T00:00:00Z',
|
||||
},
|
||||
|
||||
@@ -7,8 +7,8 @@ import AppLogo from '@/components/AppLogo.vue'
|
||||
import { useParticles } from '@/composables/useParticles'
|
||||
import type { AboutInfo } from '@/types/api'
|
||||
|
||||
// GitHub 仓库地址:开源发布后填充;空串时按钮禁用并显示占位
|
||||
const REPO_URL = ''
|
||||
// GitHub 仓库地址;空串时按钮禁用并显示占位
|
||||
const REPO_URL = 'https://github.com/wangdefaa/oci-portal'
|
||||
|
||||
const info = ref<AboutInfo | null>(null)
|
||||
const loading = ref(true)
|
||||
|
||||
Reference in New Issue
Block a user