Files

T

QiuSWandClaude Opus 5 421c865ad2 feat(tasks): adopt Vikunja as task authority with one-way export

把任务的协调状态迁到自建 Vikunja 的 cmbuyer 项目，git 保留单向投影，
并把「活跃任务写路径不得重叠」从自然语言规则变成机器门禁。

- scripts/vikunja_export.py：单向导出（只发 GET），stdlib-only 的
  HTML→Markdown，只覆盖标记区块内，幂等，含 --selftest
- scripts/vikunja-mcp.sh：MCP 启动包装从家目录迁入仓库，版本写死 1.1.1
- scripts/validate_agent_context.py：新增四项离线检查——DOING 任务写路径
  互斥、通配不得圈走共享文档、导出区块 sha256、连接键一致性
- docs/agent-context.json：新增 shared_documents 与 tracker，schema_version 2
- vikunja.env 比照 gitea.env 加入 gitignore，提交 vikunja.env.example

write_paths、## 边界与安全边界条目的权威留在 git，不迁往 Vikunja：
安全边界能否收紧靠 git diff 逐条复核，权威搬到远端会切断审计链。

门禁上线即报出存量违规：T-005 与 T-006 同为 DOING，在 06-tasks.md、
08-interaction-checklist.md、routes.md、current-state.md 四处重叠。
按 T-008 规定不得绕过，须由两者所有者收窄写路径或人工确认后转 DONE。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-03 17:00:41 +08:00

6.0 KiB

Raw Blame History

AGENTS.md

Codex / AI coding agent 的仓库级入口。进入本仓库后先读本文，再进入 docs/00-ai-start-here.md。

项目定位

cmbuyer 是一个自动化采购系统：采购服务（网页端，admin/，Go）负责建单与人工决策， 采购工具（Windows 桌面端，client/，Python）驱动 Android 手机在拼多多完成找货和下单。

系统只创建待付款订单，任何情况下都不自动付款。

当前状态：仓库只有文档，尚未开始编码。阶段为 Phase 0。

必读顺序

本文。
docs/00-ai-start-here.md：入口流程与四条特有纪律。
docs/05-coding-rules.md：第 1 节红线。
docs/current-state.md：当前代码现实与下一步任务。
与当前任务相关的具体文档（按 docs/agent-context.json 路由）。

日常会话按 agent-context.json 的 bootstrap.always_read 与任务类型 routes 读取，不机械重读全部文档。

四条不可协商的规则

1. 不碰钱

绝不编写点击支付、免密支付、先用后付或任何扣款控件的代码。这条没有例外，也不接受「先做个开关默认关掉」。

系统会点击「提交订单」创建待付款订单，但必须满足四个前置条件（授权未消费且服务端提交围栏已建立、闸门二通过、闸门三通过、控件唯一），且只点一次、点击后无论结果都不重试。围栏申请失败或响应不明时不得点击；围栏建立后只能调和同一提交记录。 第一趟试选的代码路径不得引用任何下单函数，必须有测试证明不可达。

2. 安全边界只能收紧

docs/04-architecture.md 第四节列出全部硬约束，含三道价格闸门与提交订单四条件。不得在任务中放宽任何一条，包括为了让流程跑通而临时放宽。确需变更时先改架构文档并说明理由。

价格只在规格面板和订单确认页读。别处读不到就转人工，不用其他位置的数字凑合。

3. 页面判据必须先真机取证

拼多多 App 会随版本改变页面结构。不得从前序项目、旧文档或推理直接写判据。 必须先真机 dump 取证，把截图路径、XML 路径和拼多多 App 版本写进任务文件。

4. 真机验收只能由人完成

needs_device: true 的任务，agent 不得自行标 DONE，保持 DOING 并写明等待事项。

前序项目的地位

/mnt/d/chengma/cmroubao 与 /mnt/d/chengma/cmpdd 是本项目的设计依据，不是事实来源。

可以参考它们的结构决策和护栏理由。
不得把它们的页面判据、常量或结论当作已验证事实直接使用。
引用其中任何结论时，必须在本项目重新验证并记录证据。

搬运护栏时，必须连同理由一起搬。只搬代码不搬理由，后人会把它当碍事的逻辑删掉。

工作模式

默认单任务、单责任 agent、单写入者：一个任务只有一个负责人，同时只有一个 agent 修改该任务的 write_paths。
多 agent 并行只拆到写路径互不重叠的任务。admin/ 采购服务与 client/ 采购工具天然可并行。这条不再只靠自觉：scripts/validate_agent_context.py 会拒绝两个 DOING 任务写同一路径。
共享文档只由任务所有者写入。 docs/agent-context.json 的 shared_documents 列出跨任务共享的文档；受托执行者不得直接改它们，只提交建议由所有者合入。共享文档可以出现在某个任务的 write_paths，但必须逐条显式列出，不得用通配圈走。
复杂任务先规划再编码。方案、不可变约束、写路径和验收门禁必须写入任务文件，不能只停留在对话里。
任务内委派不是默认流程。委派后仍保持唯一写入者，执行者必须继承任务文件中的不可变约束与验证要求。
无论是否委派，任务所有者都对结果负责，独立审阅差异、重跑验证； 不能把执行者或工具的自我报告当成完成证据。

任务状态存放在哪

任务的协调状态（标题、状态、标签、依赖、方案正文、执行记录）权威在自建 Vikunja 的 cmbuyer 项目；docs/tasks/T-XXX.md 里两行 VIKUNJA EXPORT 标记之间的内容是它的 单向投影，由 scripts/vikunja_export.py 覆盖写入，不要手工编辑。

write_paths、## 边界 与安全边界条目的权威始终在 git，不迁往 Vikunja。理由见本文第 2 条：安全边界能不能收紧靠 git diff 逐条复核，权威一旦搬到远端，放宽边界的改动在 diff 里只呈现为「导出内容更新」，审计链就断了。

只读任务内容不需要接入 Vikunja——导出产物就在仓库里，git clone 即可。只有写状态和执行记录才需要配置 MCP（.mcp.json → scripts/vikunja-mcp.sh，凭据见 vikunja.env.example）。

Vikunja 不可达时按 degraded_mode 处理：继续手头任务，不领新任务，不写远端。

验证

按 docs/03-tech-stack.md 第六节的验证矩阵判断层级：

# 采购服务（admin/）
go test ./...
go vet ./...

# 采购工具（client/）
python -m unittest discover -s tests -t .
python -m compileall -q src tests

# 上下文清单
python scripts/validate_agent_context.py

跨端契约改动必跑完整门禁——两端会同时坏。

代码尚未初始化，上述命令在 T-001 / T-002 完成前不可运行；届时由对应任务替换为真实命令并同步文档。

风格

文档与 UI 文案使用中文，标识符使用英文。
金额一律用十进制字符串，不用浮点数。
护栏必须连同理由一起注释。
内容面向执行，每条规则能落到「读取什么、修改什么、验证什么」。

6.0 KiB Raw Blame History Unescape Escape