跳到正文

文档与 Agent 工作流 ​

文档只描述当前实现、使用约束、关键设计理由与未验证边界。完成条件是入口可发现、链接和命令有效、事实与代码及证据一致;不追加逐轮“最新进展”,不维护已完成的迁移计划或未经确认的未来排期。

信息归属 ​

信息权威位置
项目介绍根 README;指向使用指南,不复制完整教程
用户入门与操作VitePress docs/;首页与侧边栏给出明确阅读顺序
跨任务约束与导航根 AGENTS;目录专属约束放对应 AGENTS
当前能力、验证结果与缺口status.md,保留证据日期与原始产物链接
模块职责、依赖与命名架构
包、版本、CLI 参数及检查计划清单、锁文件、parser 与 src/pride/checks.py;不手工复制平行清单
CLI 用法核心 --help 提供用途和常用例子;参数定义由 parser 维护
操作示例与截图随对应用户指南维护,示例由文档检查解析,图片位于 docs/public/images/
领域契约、原理和操作约束domain.md 与对应专题;运行字段由类型定义提供
可重复任务流程.agents/skills/<name>/SKILL.md
单次运行原件与过程日志runs/、artifacts/;不作为当前使用说明
版本化修复的因果依据与配方关联的精简技术说明,保留来源、哈希与适用范围

写给使用者 ​

入门教程按顺序完成一件事;操作指南围绕一个具体目标。先说明结果和必要前提,再给步骤、命令、画面与预期状态,最后写常见卡点。关键前提直接写在操作处,补充背景才使用链接,不让读者为一个步骤连续跳转。

技术参考维护精确字段、协议与约束;原理说明解释原因;当前状态和带日期的报告保留验证边界。必要的背景和最小命令允许在教程重复,参数大全不手工复制。CLI 帮助先覆盖核心功能,不为了完整性扩展成另一套文档系统。

截图使用真实画面,在图旁解释看哪里、操作什么、预期结果;注明日期和原始来源。发布用截图随文档版本管理,原始验收材料保留在 artifacts。站内图片用 /images/文件名.png 引用,VitePress 按原文件名发布。点击查看原图的链接末尾添加 {target="_self"},由浏览器直接打开图片,写法参照工作台教程源码。历史画面不能作为当前版本验收。界面或行为修改时核对对应指南与图片。

维护 VitePress ​

站点使用默认主题、人工侧边栏和本地搜索。配置位于 docs/.vitepress/config.mts,依赖由独立的 docs/pnpm-lock.yaml 固定,不与工作台混用锁文件。新增页面应放入合适的导航分组。正文保留普通 Markdown,不复制到另一份发布源。

sh
uv run pride build docs
npx --yes pnpm@12.18.0 --dir docs preview

本地预览地址由终端打印。日常编辑可使用:

sh
npx --yes pnpm@12.18.0 --dir docs dev

构建输出为 artifacts/docs/site/,缓存为 artifacts/docs/cache/。静态文件可由普通 HTTP 服务托管;文档通过 .github/workflows/docs.yml 在 PR 中检查,主分支更新时自动发布到 https://robotics.lantianyou.com 。发布使用 docs/cloudflare.config.ts 和 docs/wrangler.config.ts,固定 CF 与 Wrangler 版本。GitHub 仓库 secret CLOUDFLARE_API_TOKEN 提供限于本账户 Workers 和本站点 zone 的发布权限;本地 OAuth 登录不用于 CI。源码和运行产物的路径以仓库根目录为基准,在站内作为文字定位,不把整仓源码、模型或设备记录复制进网站。

修改后运行 uv run pride check docs:校验 Markdown 链接、图片、CLI 示例、skill 与检查目录,再执行锁定依赖安装和 VitePress 构建。首次安装可能联网,无需 GPU 或设备。核心 CLI 行为变更另跑对应代码检查。

检查通过后仍要检查读者路径:从首页进入教程,能否按顺序走完,截图是否清晰、搜索是否可用。构建通过只证明站点可生成,不代表真实机器人任务验收通过。

更新与验证 ​

先核对代码、配置和原始记录,再更新唯一权威位置。已实现内容写当前行为;未实现内容只在状态页保留必要的能力边界,不把设想包装为待执行任务。实验失败和未覆盖项不能因文档整理变成通过,历史数字不冒充当前版本验收。

路径和入口改变时同步调用方、链接与命令,删除旧入口。一般专题采用小写 kebab-case,入口文件及 SKILL.md 保留约定名称。保留关键取舍理由,删除“先试了什么、后来改了什么”的叙述;需要追溯时查 Git 和产物。

文档修改运行文档检查;代码、包或协议变化按验证指南执行对应检查。开发复现与回归统一走 pride check,先看结构化结果,再读失败日志。项目 Python 使用显式 uv 环境。

产物清理 ​

以完整 run 或明确的临时构建目录清理,不单独删除保留记录中的 result、manifest 或哈希覆盖文件。检查活动进程、近期写入、当前文档及保留产物的引用,递归保留模型与数据依赖。年龄本身不足以判定过期;实机故障证据、厂家来源、版本化 wheel 和在用构建环境不按临时产物删除。

每次清理在 artifacts 留下删除路径、理由与占用清单。原件不改写;保留的记录缺证据时如实报告,不补造哈希或结果。无需为一次清理新增常驻管理器。

技能与错误提示 ​

pride-verify 用于复现和验证,pride-experiment 用于固定输入与预算的实验比较。技能 description 明确触发场景;短流程放 SKILL.md,分支参考按需加载。安装来源和哈希见技能清单(artifacts/agent-check-development/skills.json)。

diagnosing-bugs 用于难复现缺陷,codebase-design 用于模块接口,tdd 用于明确的测试优先开发,modern-web-guidance 用于前端,anthropic-skill-creator 用于技能迭代。安装不授权派生 Agent、跨模型评审、外部操作或实机运动;本项目不使用 Superpowers。

新写或修改的错误提示给出具体错误值、可确定的有效选项与修复动作。区分输入错误、缺环境和执行失败;在耗时操作前校验输入。实际触发并核对输出,测试关键行为,不冻结无关措辞。