weichen
80a4fa5e32
Why: The approved frontend redesign requires a durable design constitution
so future UI work stays consistent (user directive: make this project's
standing design guidance, four principles: beautiful/modern/concise/usable).
DESIGN.md encodes the Zai-calibrated rules (surface ladder, type scale,
radius nesting, MotionKit recipes, ToolBlock contract, IA principles) and
AGENTS.md adds a mandatory UI gate; submodules land phase 1 (tokens v3,
MotionKit, Collapsible, panel layout, mono primary buttons).
Evidence: make test in this worktree -> frontend 38 passed (incl. new
host design-guard ratchet), ui 61 passed (incl. collapsible + design-guard),
go core/backend/agent-command ok. precheck READY at R0 0be23f9a4d.
Impact: gitlinks advance to Agent-System-UI/Agent-System-Frontend
feature/ui-tokens-v3 heads; AGENTS.md gains a UI section; no backend or
contract changes.
Refs: session-approved redesign plan v2 (8 decisions recorded in task card).
67 lines
5.0 KiB
Markdown
67 lines
5.0 KiB
Markdown
# Agent 工作说明（Agent-System-Dev）
|
||
|
||
本仓开发遵循 Development-Guidelines（见 `deps/development-guidelines`，gitlink 固定版本）：
|
||
核心规则与术语见其 `core/`，按任务触发阅读 `standards/` 专题；日常交付走 `workflows/delivery.md`。
|
||
|
||
## UI 设计门禁（强制）
|
||
|
||
- 本仓一切界面生成/修改**先读根目录 `DESIGN.md`**（四原则：美观、现代、简洁、易用），
|
||
再动手；违反视为设计系统缺陷，不是风格偏好。
|
||
- 颜色/圆角/字号只消费 `@ui/tokens.css` 令牌（字号走 `--fs-ui-*` 标尺）；动效只用
|
||
`@ui/motion.css` 的 `mk-*` 工具类；折叠一律用 `@ui` Collapsible 原语，禁止 `<details>`。
|
||
- 守护测试（UI 仓与 Frontend 仓各一份 `design-guard.test.ts`）以棘轮拦截新增裸色值、
|
||
私有 `@keyframes` 与行内字号；改风格 = `DESIGN.md` + 令牌文件同 PR 成对修改。
|
||
|
||
## 任务启动门禁（强制）
|
||
|
||
- 任务启动或恢复后，**第一次写操作前**运行 `make precheck` 并附完整输出；verdict 为
|
||
`SHARED_WORKSPACE_BUSY / SYNC_REQUIRED` 时不得编辑。
|
||
- 按其必读清单完成阅读，然后 `make task-start NAME=feature/<slug>` 建立独立 worktree +
|
||
feature 分支（自动记录 R0 与任务卡）；任务中途不重复运行 precheck。
|
||
- **分支层级**：任务分支一律从权威 `origin/main` 切（`task-start` 已强制）；同批互不依赖的
|
||
子任务用同一 R0 的兄弟分支。确有顺序依赖需从父 feature 分支切子分支时（collaboration.md
|
||
允许的堆叠例外）：任务卡显式记录父任务与父 PR；子分支命名 `<type>/<父slug>-<子题>`，
|
||
不嵌 SHA；合入顺序固定父→子；父合入后子分支须 `make task-sync` 并入最新 main 并把 PR
|
||
base 改回 main，方可声明可合入（分支保护要求 head 含 origin/main，未同步必被拦）。
|
||
- **验收、请求审核、合入前**各运行一次 `make task-sync`；完成声明附 precheck、task-sync、
|
||
测试三段输出。
|
||
- 合入后**在 worktree 内**运行 `make task-finish` 回收 worktree 与分支（脚本会把
|
||
当前目录当 worktree 回收——在主检出运行会误删主检出，已加防护）；放弃未合入
|
||
工作用 `make task-finish ABANDON="--abandon <原因>"` 并记录原因。
|
||
- **任务卡闭合（防欠账）**：分支合入 main 后，其任务卡须回填"已完成"+主记录 PR 链接并
|
||
归档至 `.task/archive/`。自动路径：`make task-finish` 收尾触发、主检出 pull 触发 post-merge
|
||
钩子（实测 ff-only pull 也触发）；钩子内 close 只扫主检出本地 `.task/`，远端刚合入的卡片
|
||
要等 pull 完成才能被看到，扫不到时由手动 `make task-close` 兜底。手动闭合在主检出运行→建
|
||
`feature/card-close-*` 分支+PR，任务分支内加 `FOLD=--fold` 随当前 PR 合入。
|
||
precheck 的 `[cards]` 行报告欠账，验收前应清零；闭合 PR 由所有者合入。
|
||
|
||
## 提交与 PR
|
||
|
||
- 主题行：英文祈使句一行（≤100 列，不以句点结尾）；body 写 `Why: / Evidence: / Impact: / Refs:`
|
||
四段；任务卡与 PR 描述为同一份文档。
|
||
- 跨仓 gitlink 变更须经组合验证（`make test`）后在 Dev 仓推进；受保护分支经 PR 合入。
|
||
- **高后果操作双钥匙**：改写历史、解除/变更分支保护、删除归档引用、发布版本——Agent 只准备
|
||
方案与命令，由用户确认并亲手执行；Agent 不得自行实施（baseline 硬边界 1 的授权范围要求）。
|
||
- 模块边界、公开契约与隔离档位见 `policy/modules/`（如有）与 PROJECT.md。
|
||
- 验证命令见 PROJECT.md「验证」节；完成声明须附实际命令输出证据。
|
||
- 首次克隆本仓后运行 `make setup` 启用本地 pre-commit 钩子。
|
||
|
||
## Gitea 与 Git 访问事实（2026-09-30 实测）
|
||
|
||
历史任务卡与旧脚本里的 `git-panel.u1680832.nyat.app:30319` 已失效（TLS 握手失败），
|
||
见到一律按过期处理，不要再试。当前权威通道：
|
||
|
||
- **Web / API（HTTPS）**：`https://git-home.u1680832.nyat.app:30319`（Gitea 1.27.3，
|
||
API 前缀 `/api/v1`；偶发 broken pipe / 超时，重试即可）。
|
||
- **Git over SSH**：`ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/<Repo>.git`
|
||
（.gitmodules 与各仓 origin 均为此格式）。
|
||
- **API token**：`~/.secrets/gitea`，两行键值 `URL_PREFIX=…` 与
|
||
`ACCESS_TOKEN=<40 位 hex>`；取值 `grep ACCESS_TOKEN ~/.secrets/gitea | cut -d= -f2-`，
|
||
用作 `Authorization: token <值>` 请求头。**token 值不入仓、不回显、不写进产出物**
|
||
（baseline 硬边界 2：只记录来源、字段与可用状态）。
|
||
- **SSH key**：`~/.ssh/home_gitea`（ED25519，公钥指纹
|
||
`SHA256:GYXaOXIMeloQ1fKSfdJ/ndgPQzs/Ix7Hk62ekfkfQ20`，Gitea 侧密钥名 GMKtec）；
|
||
`~/.ssh/config` 已有 `git-ssh.u1680832.nyat.app` 主机条目，克隆/推送直接可用。
|
||
- 任务卡闭合 PR（`make task-close` / `task-finish` 自动闭合）经 API 建 PR 时以
|
||
`GITEA_TOKEN` 环境变量传入同上的 token。
|