docs: 固化文档和技能中文写作规则
This commit is contained in:
Codex
@@ -1,83 +1,81 @@
|
||||
# Agent Instruction Hygiene
|
||||
# Agent 指令治理
|
||||
|
||||
This document is the long-term reference for keeping always-loaded agent instruction files small, navigable and stable. It applies to local and remote `AGENTS.md`, `CLAUDE.md`-style aliases and any repo-level instruction file that is automatically injected into an agent context.
|
||||
本文是长期参考，用于保持自动加载的 Agent 指令文件精简、可导航且稳定。适用于本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名，以及所有自动注入 Agent 上下文的仓库级指令文件。
|
||||
|
||||
## Size Budget
|
||||
## 体积预算
|
||||
|
||||
`AGENTS.md` is an index, not a knowledge base. The hard size budget for any local or remote `AGENTS.md` is 10 KiB, measured as bytes with `wc -c AGENTS.md`.
|
||||
`AGENTS.md` 是索引，不是知识库。任何本地或远端 `AGENTS.md` 的硬上限均为 10 KiB，使用 `wc -c AGENTS.md` 按字节计量。
|
||||
|
||||
When an `AGENTS.md` is already over 10 KiB, do not append more detailed rules to it. Split first, then add only a one-line index entry back to `AGENTS.md`.
|
||||
`AGENTS.md` 已超过 10 KiB 时，不得继续追加详细规则。必须先拆分，再只向 `AGENTS.md` 回填一行索引。
|
||||
|
||||
When editing an `AGENTS.md` would push it over 10 KiB, route the new content to a skill or a `docs/reference/*.md` document and keep `AGENTS.md` as a short pointer.
|
||||
修改 `AGENTS.md` 会导致其超过 10 KiB 时，把新内容分流到 skill 或 `docs/reference/*.md`，并保持 `AGENTS.md` 为短索引。
|
||||
|
||||
If loading or printing `AGENTS.md` triggers CLI output dump or context blow-up, treat that as a visibility bug and an instruction-hygiene bug. The fix is to split the file, not to increase output limits or ask agents to read around the dump.
|
||||
加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时，将其视为可见性缺陷和指令治理缺陷。正确修复是拆分文件，不是提高输出上限或要求 Agent 绕过转储读取。
|
||||
|
||||
## What Belongs In AGENTS.md
|
||||
## AGENTS.md 应包含的内容
|
||||
|
||||
Keep only always-needed routing information in `AGENTS.md`:
|
||||
`AGENTS.md` 只保留始终需要的路由信息：
|
||||
|
||||
- Project identity and source-of-truth boundaries.
|
||||
- P0 one-line rules that prevent immediate damage.
|
||||
- Links to the authoritative long-term reference document for each domain.
|
||||
- Skill names that must be loaded for common workflows.
|
||||
- Short warnings about secrets, destructive commands, target workspaces and build bans.
|
||||
- 项目标识和真相源边界；
|
||||
- 防止直接损害的一行 P0 规则；
|
||||
- 各领域权威长期参考文档链接；
|
||||
- 常用工作流必须加载的 skill 名称；
|
||||
- Secret、破坏性命令、目标工作区和构建禁令的短警告。
|
||||
|
||||
Do not put long examples, command transcripts, JSON output, issue timelines, architecture essays, provider-specific debugging logs or one-off incident analysis in `AGENTS.md`.
|
||||
不得放入长示例、命令记录、JSON 输出、issue 时间线、架构长文、provider 特定调试日志或一次性事故分析。
|
||||
|
||||
## Where Overflow Content Goes
|
||||
## 超出内容的分流位置
|
||||
|
||||
Use this routing order when splitting content out of `AGENTS.md`:
|
||||
拆分 `AGENTS.md` 时按以下顺序分流：
|
||||
|
||||
- Reusable workflow behavior belongs in a skill `SKILL.md`, for example `$dad-dev`, `$unidesk-cicd`, `$unidesk-gh`, `$unidesk-trans`, `$unidesk-otel`, `$unidesk-webdev` or `$unidesk-ymalops`.
|
||||
- Stable project constraints, workspace rules, architecture boundaries and validation criteria belong in `docs/reference/*.md`.
|
||||
- CLI shape, output style, route syntax and operator ergonomics belong in `docs/reference/cli.md` unless a narrower reference already owns them.
|
||||
- Deployment hygiene, fixed repo boundaries and source-of-truth rules belong in `docs/reference/devops-hygiene.md`.
|
||||
- Node/lane-specific HWLAB rules belong in `docs/reference/hwlab.md` and the target repo's own reference docs.
|
||||
- AgentRun source-truth and deployment-lane rules belong in `docs/reference/agentrun.md`.
|
||||
- Platform-infra and YAML-first operations belong in `docs/reference/platform-infra.md` and `docs/reference/yaml-first-ops.md`.
|
||||
- Process notes, temporary findings and dated investigation logs belong in GitHub issues, PR comments or process notes; they must be distilled before entering long-term reference.
|
||||
- 可复用工作流进入 skill `SKILL.md`，例如 `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`、`$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev` 或 `$unidesk-ymalops`。
|
||||
- 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。
|
||||
- CLI 形态、输出样式、路由语法和操作体验进入 `docs/reference/cli.md`，已有更具体参考文档时进入具体文档。
|
||||
- 部署治理、固定仓库边界和真相源规则进入 `docs/reference/devops-hygiene.md`。
|
||||
- HWLAB 节点/通道规则进入 `docs/reference/hwlab.md` 和目标仓库自身参考文档。
|
||||
- AgentRun 真相源和部署通道规则进入 `docs/reference/agentrun.md`。
|
||||
- 平台基础设施和 YAML-first 运维进入 `docs/reference/platform-infra.md` 与 `docs/reference/yaml-first-ops.md`。
|
||||
- 过程记录、临时发现和带日期调查日志进入 GitHub issue、PR 评论或过程记录；进入长期参考前必须蒸馏。
|
||||
|
||||
If a rule is both reusable across projects and specific to UniDesk's current directories or services, put the reusable workflow in the skill and put UniDesk-specific paths, lane names and validation boundaries in `docs/reference/*.md`, then cross-reference both.
|
||||
规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时，把可复用流程放入 skill，把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`，并双向交叉引用。
|
||||
|
||||
## Split Procedure
|
||||
## 拆分步骤
|
||||
|
||||
When an agent sees a local or remote `AGENTS.md` over 10 KiB:
|
||||
Agent 发现本地或远端 `AGENTS.md` 超过 10 KiB 时：
|
||||
|
||||
1. Identify the detailed section being changed or expanded.
|
||||
2. Move the detailed content to the owning skill or `docs/reference/*.md` document.
|
||||
3. Replace the original section with one concise bullet and a link to the authoritative location.
|
||||
4. Preserve P0 damage-prevention warnings in `AGENTS.md`, but compress them to one-line routing rules.
|
||||
5. Do not create a single giant overflow archive as the normal solution. A temporary migration note is acceptable only if it immediately points to the domain documents that must absorb it.
|
||||
6. Do not add tests, guards or preflight checks just to enforce the size budget unless the user explicitly asks. The default control is documentation hygiene plus concise review.
|
||||
1. 识别正在修改或扩展的详细领域。
|
||||
2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。
|
||||
3. 用一条简短索引和权威链接替换原详细章节。
|
||||
4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。
|
||||
5. 不得把所有内容移入单个巨大溢出文档。临时迁移记录仅在立即指向各领域承接文档时可用。
|
||||
6. 用户未明确要求时，不为体积预算新增测试、保护代码或预检。默认控制方式是文档治理和简洁评审。
|
||||
|
||||
For large legacy files, split incrementally by domain. Each new edit should leave the touched domain smaller and better referenced than before.
|
||||
大型旧文件按领域逐步拆分。每次编辑都应让涉及领域更精简、引用更清晰。
|
||||
|
||||
## Cross-Reference Requirements
|
||||
## 交叉引用要求
|
||||
|
||||
Every `AGENTS.md` index entry that points out of the file must name the authoritative target. Prefer direct paths such as `docs/reference/hwlab.md` or skill names such as `$unidesk-cicd`.
|
||||
`AGENTS.md` 中指向外部的每条索引必须注明权威目标。优先使用 `docs/reference/hwlab.md` 等直接路径或 `$unidesk-cicd` 等 skill 名称。
|
||||
|
||||
Avoid duplicated full rules between `AGENTS.md`, skills and long-term reference docs. `AGENTS.md` may summarize; the reference owns the detail. If two references conflict, update the narrower domain reference and keep only one authoritative version.
|
||||
不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则。`AGENTS.md` 可以摘要，参考文档拥有细节。两个参考文档冲突时，更新职责更具体的文档，并只保留一个权威版本。
|
||||
|
||||
## Secrets And Output Hygiene
|
||||
## Secret 与输出治理
|
||||
|
||||
Instruction files must not contain secrets, full API keys, full DSNs, base64 payloads, bearer tokens, SSH private keys or copy-pastable credentials.
|
||||
指令文件不得包含 Secret、完整 API key、完整 DSN、base64 载荷、bearer token、SSH 私钥或可直接复用的凭据。
|
||||
|
||||
Do not paste large CLI output, OTel trace dumps, JSON arrays or browser transcripts into `AGENTS.md`. If a large output demonstrates a durable rule, summarize the rule and link to the issue or reference that owns the conclusion.
|
||||
不得把大段 CLI 输出、OTel trace 转储、JSON 数组或浏览器记录粘贴进 `AGENTS.md`。大输出证明可复用规则时，只保留规则摘要，并链接到拥有完整结论的 issue 或参考文档。
|
||||
|
||||
## Current UniDesk Routing Map
|
||||
## 当前 UniDesk 路由图
|
||||
|
||||
The current top-level routing map is:
|
||||
|
||||
- CLI behavior and output: `docs/reference/cli.md`.
|
||||
- YAML-first configuration: `docs/reference/yaml-first-ops.md` and `$unidesk-ymalops`.
|
||||
- Platform infrastructure: `docs/reference/platform-infra.md` and `$unidesk-sub2api` when Sub2API is involved.
|
||||
- Distributed field repair: `$dad-dev` plus `docs/reference/devops-hygiene.md`.
|
||||
- CI/CD and rollout: `$unidesk-cicd` plus `docs/reference/cli.md`.
|
||||
- GitHub issue and PR writes: `$unidesk-gh`.
|
||||
- Trans/remote patch transport: `$unidesk-trans` plus `docs/reference/cli.md`.
|
||||
- Web UI, Workbench and web-probe: `$unidesk-webdev`.
|
||||
- OpenTelemetry and Tempo: `$unidesk-otel` plus `docs/reference/observability.md`.
|
||||
- HWLAB node/lane operation: `docs/reference/hwlab.md`.
|
||||
- AgentRun: `docs/reference/agentrun.md`.
|
||||
- Master/D601 development environment: `docs/reference/dev-environment.md`.
|
||||
- Secretary work: `docs/reference/secretary-reference.md`.
|
||||
- CLI 行为与输出：`docs/reference/cli.md`。
|
||||
- YAML-first 配置：`docs/reference/yaml-first-ops.md` 与 `$unidesk-ymalops`。
|
||||
- 平台基础设施：`docs/reference/platform-infra.md`；涉及 Sub2API 时使用 `$unidesk-sub2api`。
|
||||
- 分布式现场修复：`$dad-dev` 与 `docs/reference/devops-hygiene.md`。
|
||||
- CI/CD 与发布：`$unidesk-cicd` 与 `docs/reference/cli.md`。
|
||||
- GitHub issue 与 PR 写入：`$unidesk-gh`。
|
||||
- Trans/远端补丁传输：`$unidesk-trans` 与 `docs/reference/cli.md`。
|
||||
- Web 界面、Workbench 和 web-probe：`$unidesk-webdev`。
|
||||
- OpenTelemetry 与 Tempo：`$unidesk-otel` 与 `docs/reference/observability.md`。
|
||||
- HWLAB 节点/通道运维：`docs/reference/hwlab.md`。
|
||||
- AgentRun：`docs/reference/agentrun.md`。
|
||||
- Master/D601 开发环境：`docs/reference/dev-environment.md`。
|
||||
- 秘书工作：`docs/reference/secretary-reference.md`。
|
||||
|
||||
Reference in New Issue
Block a user