codex-bot
db4b00bad0
waterfall-wiki CI and deployment / verify-and-deploy (pull_request) Has been cancelled
57 lines
4.7 KiB
Markdown
57 lines
4.7 KiB
Markdown
# Linked Guidance 0.1 — 提案，名称待定
|
||
|
||
目标是让任何一篇文档都能作为 coding agent 或 personal agent 的入口。不需要安装目录、不要求加载集合、不通过仓库位置继承权限。集合只是书签，不是执行单元。
|
||
|
||
## 文档语法
|
||
|
||
使用 UTF-8 XML 1.0；媒体类型 application/xml。正文与步骤使用纯文本，XML 转义适用于全部文本和属性；不允许 DTD、外部实体、处理指令和可执行嵌入。0.1 的标准输出由服务端生成，不接受任意 XML 上传执行。
|
||
|
||
```xml
|
||
<guidance xmlns="urn:linked-guidance:0.1" id="review-changes" revision="1" kind="guide" lang="zh-CN">
|
||
<title>审查一次代码变更</title>
|
||
<summary>定位实际影响，并给出可验证的审查结论。</summary>
|
||
<applies>用户请求 review、检查变更或评估回归风险。</applies>
|
||
<body>先阅读需求与完整差异，再追踪受影响的调用路径。</body>
|
||
<step>按影响排序，只报告有证据的问题。</step>
|
||
<link target="test-changes" revision="1" relation="guide" when="需要选择验证方法">选择适当测试</link>
|
||
<link target="source-trust" revision="1" relation="context" when="变更包含外部资料">判断资料可信度</link>
|
||
<check>每个结论能指出具体触发条件与验证方法。</check>
|
||
</guidance>
|
||
```
|
||
|
||
根元素必需属性：命名空间、id（小写字母、数字与短横线）、正整数 revision、kind（guide/context/evidence）、lang。必需单值子元素：title、summary、applies、body。step、link、check、tag 可重复；tag 为纯文本发现标签，不授予执行语义。未知版本必须明确拒绝，不能猜测执行。正文只提供文本，展示层的 HTML 不属于协议。
|
||
|
||
## 链接与读取
|
||
|
||
链接是候选阅读建议，不能自动授予权限，也不是强制依赖。`when` 是自然语言条件，由 agent 结合当前任务判断。relation=guide 表示可能有用的指导；context 表示背景；evidence 表示事实依据。后两者不能升级成操作指令。即使 guide 链接也只能在用户授权范围内采用。
|
||
|
||
先读入口文档自身，再看链接摘要；满足条件且确实缺少相关知识才读取目标正文。单次读取预算默认 8 篇、最大深度 3，以 (id,revision) 去重；记录读取原因、跳过原因、未知版本和缺失目标。预算耗尽时停止扩展并报告不完整。不得把循环、链接失效理解为任务失败；必需前置条件不满足时停止相应动作并说明。
|
||
|
||
0.1 target 仅允许本站逻辑 id，不自动请求任意 URL；避免服务器端网络探测。外部来源只作为显式资料链接展示，后续联邦协议需要单独定义域名信任、重定向、内容大小与哈希规则。
|
||
|
||
## 版本与可信度
|
||
|
||
固定 revision 是精确引用，缺失时不得静默切换最新版。latest 仅用于发现，实际采用前解析为固定版本。已发布版本不可原地修改；更新创建新版本，旧链接继续可解析。文档、集合、作者、运行时权限分别管理。引用任何作者的文档都不会获得作者权限。
|
||
|
||
用户指令与运行环境规则优先。文档中的联网、发送邮件、运行命令、发布和删除步骤都需要现有任务授权。文档不能要求 agent 忽略更高优先级指令或获取秘密。
|
||
|
||
## HTTP
|
||
|
||
- GET /llms.txt 与 /agent/index.md：公开发现入口，说明如何只选择一篇并按条件继续读取；/index.md 指向同一入口。
|
||
- GET /api/documents：真实发布内容的摘要，不加载所有正文。
|
||
- GET /api/documents/:id?revision=1：真实文档精确版本 JSON；format=xml 获取规范 XML。
|
||
- GET /documents/:id?revision=1：真实文档的人类阅读视图。
|
||
|
||
以下 /api/guides 与 /guide 路径只提供协议样例，不能将它们误认为完整用户内容目录。
|
||
|
||
- GET /api/guides：发现摘要、种类和固定版本，不包含整套正文。
|
||
- GET /api/guides/:id?revision=1：单篇 JSON；format=xml 获取单篇规范 XML。
|
||
- GET /guide/:id：人类阅读界面，单篇正文、条件链接、反向链接、版本。
|
||
- 每次 agent 采用文档时记录实际版本与来源，而不是只记录集合名称。
|
||
|
||
0.1 是最小可检验原型，不宣称现有 agent 已原生支持。agent 可通过阅读 XML 采用约定；MCP、编辑器插件、联邦索引属于后续适配。
|
||
|
||
## 研究依据
|
||
|
||
Karpathy 的原始提案 https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f 描述 raw/wiki/schema、ingest/query/lint 和持久交叉引用。本方案借鉴持久链接与渐进读取，新增独立指导单元、条件链接、关系类型、明确版本和授权边界。它不是该提案的原有 XML 标准。
|