agents

Imported from Gaarahan/dotfiles (agents/AGENTS.md). Install upstream with npx skills add Gaarahan/dotfiles --skill agents. Copyright stays with the author.

~/.agents 全局规范（VibeCoding）

本目录用于管理你本机的 Agent 行为规范与可复用技能（skills），目标是：

• 可移植：跟随 dotfiles，一次配置，多机复用
• 可组合：把能力拆成小技能，每个技能都有清晰的输入/输出与边界
• 可审计：技能尽量复用本仓库的脚本（例如 bin/tools/*），避免“黑盒”行为

目录约定

• ~/.agents/AGENTS.md

  • 你个人的“全局协作约定”（提问/改码、输出风格、默认偏好、允许的副作用等）
  • 作用范围：对所有项目生效

• ~/.agents/skills/<skill-name>/SKILL.md

  • 某个技能的规格说明（Skill Spec）
  • 文件名固定：SKILL.md

• ~/.agents/tools/<tool-name>/...

  • skill 会复用的“工具实现”（脚本/小程序），尽量做到可审计、可复用
  • 对外提供稳定入口时，建议配套一个 dotfiles/bin/tools/<cmd> 作为 shim

SKILL.md 模板（建议结构）

1. 技能简介：一句话描述 + 典型使用场景
2. 入口/命令：CLI 命令、脚本路径、或 API
3. 输入：参数、stdin、环境变量、配置文件
4. 输出：stdout/stderr、退出码、产物文件
5. 依赖：运行时（Node/Python/Go）、网络、权限
6. 示例：3-5 个常用用例（含失败示例）
7. 安全与边界：隐私、默认行为、避免误触发的约束
8. 排障：常见报错、如何验证、如何清理缓存

与 dotfiles 的集成方式

本仓库推荐把 skills 放到 dotfiles/agents/ 下，并通过安装脚本把它软链到 ~/.agents，与 ~/.zshrc / ~/.tmux.conf 的管理方式一致。

~/.agents 是指向 dotfiles/agents 的软链，所以本文件（~/.agents/AGENTS.md）与 dotfiles/agents/AGENTS.md 是同一份、由 dotfiles 的 git 跟踪。改全局规则直接改本文件并在 dotfiles 提交即可，不要把它挪到 skill 仓库（挪走后运行时读的仍是软链指向的这份，且它不是 skill 格式、不会被加载）。

自定义 skill 的源与同步（重要，避免放错仓库）

自定义 skill 按能力分为两个权威来源：

• 文档协作 skill：gh-lark-tech-doc-writing 与 gh-lark-comment-doc-editing 的唯一权威源位于本仓库 skills/。两者作为一个 collection 共同维护，并共享 gh-lark-tech-doc-writing/references/readability-principles.md。修改时只改本仓库中的源文件。
• 其他 gh- skill：唯一权威源仍是 code.byted.org:hanzhaofeng/dotfile-skills（本地 ~/Documents/dotfile-skills），布局为 skills/<gh-name>/SKILL.md。新增或修改这些 skill 只在该源仓库进行。
• 运行时入口：~/.agents/skills/（= dotfiles/agents/skills/）与 ~/.trae-cn/skills/ 是运行时目录，不是文档协作 skill 的维护位置。运行 bin/tools/sync-document-skills，将两个运行时入口链接到本仓库的权威源。
• 同步流程：修改文档协作 skill 后，运行 bin/tools/sync-document-skills 并执行校验；修改其他 gh- skill 后，在 dotfile-skills 中 commit/push，再执行 npm_config_registry="https://bnpm.byted.org" npx -y agentbuddy@latest skill add skills.bytedance.org/hzf/dot_skills --yes --global。agentbuddy 可能替换文档协作 skill 的运行时链接，因此重装后必须再次运行 bin/tools/sync-document-skills。

完备性约束（重要）

当修改任意 skill 相关内容时，必须保证“脚本、入口、文档”同步更新，避免出现：文档说 A、实际跑出来是 B 的情况。

• 技能规格：以该 skill 的权威源为准；文档协作 skill 位于本仓库 skills/<skill-name>/SKILL.md，其他 gh- skill 位于 dotfile-skills 的 skills/<skill-name>/SKILL.md
• 工具实现：agents/tools/<tool-name>/...
• 稳定入口（如有）：bin/tools/<cmd>（通常只做转发/shim）
• 校验方式：至少运行一次 --help / --show-config（或该工具的等价自检命令），确保文档与输出一致

协作约定（提问 vs 改码）

• 当你向我 提问（例如：问原理、问哪里改、让解释代码、讨论方案）时：即使我已经知道如何修改，也不要直接改代码/落盘变更。允许执行用于定位问题的只读命令（例如：git diff/git status/rg/ls），但不应产生文件改动、提交、推送等副作用；若确需修改，再由你明确提出“要改代码”。
• 当你明确提出 要改代码（例如："请修改/修复/实现/重构/提交"）时：我才进入实现流程（改代码、补测试、运行验证等）。
• 完成用户明确要求的代码修改并通过必要验证后，默认只暂存本次任务涉及的改动并创建 commit；不暂存用户的无关改动，不使用 git add -A。默认不执行 git push，推送需要用户明确授权。
• Git 提交默认不允许使用 --no-verify：除非你明确指出可以绕过 hook，否则我只能按正常 git commit 提交；若 hook 失败，我应反馈失败原因，而不是自行跳过校验。
• 当你明确让我拉分支时：我应根据本次要做的工作类型默认创建语义化分支名；功能开发优先使用 feat-xxx，缺陷修复优先使用 fix-xxx，并让分支名直接体现本次任务主题。
• 当你修正我的做事方式、默认偏好或协作习惯时：若该修正显然是跨项目通用规则，我应主动更新 ~/.agents/AGENTS.md，而不是只在当前对话里记住；若该修正明显依赖当前仓库上下文，则应写入项目 AGENTS.md 或仅在当前项目内遵循。
• 当你要求我**“沉淀”某项经验或再次“强调”某个问题**时：默认表示需要修改对应的可复用协作约束以避免以后再犯。我必须在本轮定位规则的唯一权威文件，写入可执行约束并回读验证；仅修当前产物、口头确认或只写云记忆不算完成。
• 当修正内容对应某个可复用 Skill 的执行流程时：优先修改该 Skill 的源仓库规格，并按同步流程更新运行时副本；全局记忆只能作为辅助提示，不作为主生效机制。不要为了覆盖不同客户端而逐个修改 Codex、TRAE、Cursor 等私有配置。
• 若需求表达不明确：优先按“提问模式”处理，先澄清是否需要落地改动。
• 当语义、状态、场景或关键输入没有被明确确认时：默认不要擅自兜底成看似合理的值；应优先发起澄清。若当前链路不适合澄清或已进入执行阶段，则显式报错或暴露缺失前提，而不是无脑回退到默认值。
• 写代码时优先依赖已经建立的类型与上游契约：若某个函数/字段的契约已经确定，就不要在下游重复写 Array.isArray、空值兜底、默认值回退等防御式代码。若我对契约没有信心，应先修正契约、类型或源头校验，再决定是否需要运行时保护，而不是把怀疑摊到每一层。
• 涉及代码改造时：除非你显式要求我“修改代码/修复 bug”，否则我只做方案讨论；在你明确同意方案后，才会动手修改代码。

文档写作约定

• 面向读者的最终文档，只写最终状态、最终设计和最终行为，不要写修改轨迹、比较过程或协商过程。
• 避免把“这次怎么改过来”的过程语言写进正文，例如：不止……还……、不是……而是……、继续……、改成……、改为……、之前……现在……。
• 优先写成“对象 + 职责 + 机制”的结果态表达，让第一次阅读文档的人无需了解修改历史也能直接理解系统。
• 如果一句话可以直接描述事实，就不要用对比句或纠偏句。示例：
  • 避免：这些检查点不只包含进入新一轮 agent loop / step 前，还包括模型流式响应处理中、工具执行前后……
  • 优先：agent-prototype 在多个协作式取消检查点感知 signal.aborted，包括 agent loop、模型流式响应处理、工具执行前后和主循环推进边界。
• 写方案、aidocs、README、注释说明等面向读者的文本时，默认先做一轮“去变更痕迹、去过程语言、去冗余对比”的收敛，再输出最终版本。

长任务处理（硬约束，所有 Agent 必须遵守）

• Agent 回合一旦结束，就无法主动发起新会话。因此执行长任务（后台批跑、评测、长时间等待等）时，只有两条合法路径，二选一：
  1. 前台阻塞：用阻塞方式守住主会话直到任务跑完，中途绝不结束回合，跑完在同一对话里直接出结果；
  2. 飞书通知：若必须结束回合，则任务完成后通过飞书 CLI（lark-im）主动通知我，消息包含任务、当前状态、关键结论与产物链接。
• 绝对禁止「结束回合后再主动回来汇报」——这条在物理上做不到，等同于任务失联。
• 不要把这条只写进云记忆 / user_profile.md：云记忆只对单个 Agent 生效。此规则必须落在本文件，确保所有 Agent（Codex / TRAE / Cursor 等）都能读到并遵守。

Browser 自动化默认会话（agent-browser）

• 为了复用 SSO/ArcoSite/Aime 等站点登录态，后续所有 agent-browser 操作默认统一使用 --session-name work-session。
• --session-name 用于“跨重启持久化”的 cookie/localStorage；如需并行隔离任务，仍可按需使用 --session <name>（不影响持久会话名）。
• 如需彻底重置登录态：删除 ~/.agent-browser/sessions/work-session-*.json（或临时改用其它 --session-name）。

全局 AGENTS.md vs 项目 AGENTS.md

• 全局 ~/.agents/AGENTS.md：对所有项目都生效的通用协作规则与偏好（例如：提问时不落盘改动、输出格式偏好、默认交互方式）。当全局与项目规则冲突时，以项目 AGENT.md 为准。
• 项目内 agents.md / AGENTS.md：仅对当前仓库生效的项目上下文与规范（架构说明、目录约定、测试命令、关键链路、改动建议等）。你在这个项目里的行为应优先遵循它。
• 你怎么提：
  • 说“全局 AGENTS.md”：指 ~/.agents/AGENTS.md
  • 说“项目 AGENTS.md” 或 “AGENTS.md”：指仓库内的 agents.md 或 AGENTS.md（以实际文件存在为准）