中文版为默认入口。English version: README.en.md
在线阅读中文版：https://shelf.notta.uk/book/6f8d032b-5775-43a1-ab7f-1e0c98da8e38
syntax-skill 是一个可复用的 Codex skill。它以 Edward A. F. Gibson 的《Syntax: A Cognitive Approach》为理论基础，把语言形式、依存结构、记忆、上下文、噪声、规划和验证等概念，转化为可用于 AI 与 Agent 架构设计的方法论。
它适用于语言只是问题一部分的系统：长期记忆、对话管理、任务拆解、任务规划、工具调用、结果验证、不确定性处理和多 Agent 协作。它帮助设计者在继续增加 prompt 之前，先回答一个更基础的问题：语言模型之外，还需要哪些结构、状态、证据和控制循环？
Skill 由一个主入口、一个共享的 Agent 设计协议，以及八个可独立读取的领域参考组成：
- 形式与意义的分离：不要把流畅语言直接当成真实世界状态。
- 依存结构与任务表示：把用户请求转化为实体、动作、约束和依存关系构成的类型化任务图。
- 噪声信道与鲁棒推断：把输入、检索、工具和执行都看成可能出错的通信信道。
- 有损记忆与可恢复上下文：允许压缩记忆，但必须保留来源、置信度、范围和恢复路径。
- 局部性与状态引用距离：让关键事实靠近使用它们的动作，降低长上下文中的引用干扰。
- 规划与语言生成分离：把任务图、规划、执行、验证和最终措辞拆开。
- 多维 Agent 评估：分别评价任务理解、事实 grounding、工具选择、执行、验证、校准和修复能力。
- 候选生成与最终裁决分离：让 LLM 提出候选，让工具、规则、验证器和人来决定是否接受。
共享的 Agent 设计协议 负责把这八个领域组合起来，定义统一状态模型、领域卡片规范、从观察到验证的控制循环、风险敏感的决策门槛、架构输出格式和反证测试。
这本书最重要的启发，可以压缩成一句话：语言形式是通向意义的结构化线索，但不是意义本身；可靠的理解必须依赖结构、上下文、记忆、世界状态和验证。
围绕这句话，本项目提炼出以下方法论内核：
- 形式不等于意义：流畅的语言输出只能说明形式建模成功，不能自动证明事实、指称、意图或世界状态正确。
- 理解依赖结构：句子不是词语的平面排列，用户请求也不应只保留为一段自然语言；应转换为实体、动作、参数、约束和依存关系组成的任务图。
- 输入是带噪信道：用户表达、语音识别、检索、模型生成和工具结果都可能失真。系统应区分观察到的信号、候选解释、先验假设和已验证事实。
- 记忆可以有损，但必须可恢复：摘要可以压缩文字，却不能丢失来源、置信度、范围、时间和重新检索原文的路径。
- 关键依赖应保持局部：需要共同参与决策的实体、参数和约束，应靠近当前动作和当前阶段，减少长上下文中的引用距离与干扰。
- 规划不能被生成替代：模型可以提出解释、计划和工具参数，但计划必须经过前置条件、权限、风险和后置条件检查。
- 接受度是多维的：系统质量不能只用“正确/错误”衡量，还要分别评价理解、 grounding、工具选择、执行、验证、不确定性和修复能力。
- 最终裁决必须外置：LLM 适合生成候选，不应独自裁决事实、权限、安全性或任务完成状态；这些判断应交给证据、工具、规则、验证器或人。
因此，本项目不是把语言学术语直接类比成软件模块，而是把它们转化为一套设计纪律：先建结构，再做推断；先保留不确定性，再做承诺；先执行并验证，再生成最终叙述。 完整抽象见 references/core-methodology.md。
除了八个直接对应的设计领域，这本书还提供了几条更广泛的架构启发：
- 反对把流畅性当成智能：语言表达得自然，只能说明形式生成能力较强，不能证明系统已经理解现实、事实和用户意图。
- 把结构放在模型之前：很多 Agent 问题不是模型不够大，而是系统没有显式保存实体、关系、约束、时间和任务阶段。
- 重新定义记忆：记忆不是保存最多历史，而是保存最有用的依存关系，并且保留来源、时间、置信度和恢复路径。
- 长上下文不等于强理解：上下文越长，干扰和错误绑定的可能性也越大；关键事实必须被局部化、重新绑定和验证。
- 把 Agent 看成通信系统：输入、检索、生成、工具和执行都可能引入噪声，因此系统需要在推断、追问、调用工具和停止之间做风险敏感的选择。
- 把可靠性定义为可恢复性：可靠 Agent 不是永远给出答案，而是在不确定时保留不确定，在失败后能够定位、修复和重规划。
- 用实验而不是演示判断架构：一个漂亮的 demo 不能证明架构正确；需要反例、压力测试、分阶段指标和可证伪的假设。
- 把界面也当成认知系统的一部分：当前任务、关键参数、待确认事项、已完成步骤和证据来源，都应该帮助用户与 Agent 共同维护结构化状态。
这些价值可以进一步浓缩为：AI 的核心问题不是能否生成语言，而是能否在有限资源、噪声和不确定性中，稳定地构造、维护、验证并执行意义。
本项目包含整本书的翻译、分章校验、EPUB 结构修复、全书质量 review 和最终发布验证。以下是基于实际 EPUB 文本量与工作流程的估算，不是某个模型后台账单的精确读数：
| 阶段 | 估算消耗 |
|---|---|
| 英文原书第 1–11 章输入 | 约 12.4 万 tokens |
| 中文第 1–11 章译文输出 | 约 13.9 万 tokens |
| 初始结构理解与翻译规划 | 约 2–5 万 tokens |
| 初次翻译与术语维护 | 约 35–50 万 tokens |
| 分章双语校验与局部返工 | 约 20–35 万 tokens |
| XML、链接、图片、页码和 EPUB 重建 | 约 3–8 万 tokens |
| 全书质量 review 与最终验证 | 约 15–30 万 tokens |
综合估算：完整翻译和质量流程约 80 万–130 万 tokens；如果把重复读取、上下文切换、工具输出和局部返工都计入，宽口径上限可能接近 150 万 tokens。只做一次未经充分复核的速度模式初译，理论上约需 35–55 万 tokens，但不能代表最终质量。
估算使用偏新的 o200k tokenizer 对实际 EPUB 文本进行近似；不同模型、上下文复用策略和工具封装方式会造成差异。这里记录的是可复用项目的工作量级，目的是帮助读者理解“完整翻译 + 结构保真 + 质量复核”远高于单次文本生成。
语言系统最容易犯的根本错误，是把“句子说得通”误认为“任务已经解决”。这个 Skill 提供了一套更稳健的设计语言：
- 对话管理器可以把每轮对话看成依存任务图的证据，而不是孤立 prompt。
- 记忆系统可以压缩上下文，同时保留回到原始证据的路径。
- 规划器可以显式保存承诺、前置条件和后置条件，而不是把它们藏在生成文本里。
- 工具型 Agent 可以明确判断什么时候推断、什么时候追问、什么时候验证。
- 评估系统可以区分“理解错了”“规划错了”“工具失败了”和“结果没有验证”。
这不是一本直接给出现代 Agent 软件架构的书，而是一套从语言与认知理论中提炼出来的架构方法。仓库中的工程规则会明确标注为基于原文的设计应用，而不是伪装成书中的直接结论。
每个领域参考都包含：
- 书名与作者；
- 章节与小节；
- 印刷页码范围；
- 原始 EPUB 的 XHTML 文件；
- 小节锚点和页码锚点，例如
#hsec10-1、#pg_274； - 用于重新检索上下文的关键词。
完整引用地图见 references/source-map.md。引用基于英文原书的实际 EPUB 结构，而不是摘要或重新抄写的段落。仓库不复制整本书。
本仓库提供可追溯的书籍资源入口，但不把整本中文译本直接公开打包进仓库：
- 中文译本在线阅读：NottaShelf 书籍页面。
- 英文原书的官方开放获取入口、出版社信息和许可证见 references/source-assets.md。
- 中文译本的本地文件名、SHA-256、章节锚点映射和私有资源接入方式也记录在该文件中。
- 中文译本属于原书的翻译改编版本，公开再分发需要额外的授权；因此 GitHub 仓库只保存索引和引用协议，不保存整本译本。
- 仓库中的引用始终指向原始 EPUB XHTML 文件、章节锚点和页码锚点，便于 Agent 回读上下文。
本仓库同时支持 Codex 和 Cursor：
将 syntax-skill 目录复制到 Codex skills 目录，或者安装后使用 $syntax-skill 显式调用。标准 skill 元数据保持自动发现，不需要额外配置。
直接在 Cursor 中打开本仓库即可使用项目规则 .cursor/rules/syntax-skill.mdc。Cursor 会根据规则描述判断何时加载它；也可以在对话中手动引用该规则。规则会引导 Cursor 先读取 SKILL.md 和 references/agent-design-protocol.md，再按当前任务选择需要的领域文件。
如果要把它用于其他 Cursor 项目，可以复制以下内容到目标项目：
.cursor/rules/syntax-skill.mdc；SKILL.md；references/目录。
这样规则中的相对路径和原文引用索引仍然有效。
典型用途包括：
- 设计助手的长期记忆架构；
- review 会在多轮对话中丢失实体绑定的对话管理器；
- 建立任务拆解和任务规划协议；
- 设计工具调用、执行和验证闭环；
- 为多 Agent 工作流建立分阶段评估指标；
- 判断某个 LLM 输出是否需要 grounding、检索或人工确认；
- 把自然语言请求转化为包含证据要求和确认门槛的类型化任务图。
仓库包含一个可运行的 Next.js 示例：examples/syntax-agent-workbench。它把本 Skill 的方法论变成一个最小可交互产品：
- 左侧约三分之二包含两种互补图：认知流程状态图，以及会随对话演化的业务认知图谱；
- 认知流程图回答“下一步做什么”，业务认知图谱回答“系统知道哪些实体、对象类型和关系”；
- 右侧是结构化架构助手，可以通过对话更新左侧节点；
- 模型 patch 可以同时更新流程节点、实体、关系和待解决问题；
- 没有 API Key 时可以直接使用本地演示模式；
- 配置 API Key 后，前端调用 OpenAI-compatible 的
/chat/completions接口； - 支持复制 JSON、导出当前状态、重置工作区和显示待解决依赖。
使用 gpt-5.5 对一个复杂的企业报销审批场景进行了真实测试：员工提交报销单和发票，Agent 抽取字段、校验政策，金额超过 5000 元时路由给部门经理，异常时追问或转人工，审批通过后才写入财务系统，并生成审计记录和可撤销记忆。
这次测试验证了三件事：
- 流程图能够表达抽取、核验、路由、审批、写入和审计之间的状态依存关系；
- 业务认知图谱能够抽取角色、报销单、发票、政策版本、审批记录、财务系统、审计记录和人工复核等实体；
- 经过“限制实体 / 关系数量 + 限制详情长度 + JSON 尾部容错”的优化后，复杂响应可以稳定解析并落入前端状态。
本次真实请求的结果摘要：6 个流程节点更新、12 个业务实体新增、18 条业务关系新增，gpt-5.5 返回 HTTP 200，结构化 JSON 成功解析。演示状态保存在 examples/syntax-agent-workbench/src/app/agent-state.json 中。
启动示例：
cd examples/syntax-agent-workbench
pnpm install
pnpm dev打开终端显示的本地地址后，在“连接设置”中填写 API Base URL、API Key 和模型名称。Key 只保存在浏览器 localStorage，没有写入代码，也没有放入 Git；实际部署时还应根据服务商要求配置 CORS，生产环境更建议使用服务端代理或短期令牌。
运行：
python3 /Users/ruska/.codex/skills/.system/skill-creator/scripts/quick_validate.py /path/to/syntax-skill
python3 /path/to/syntax-skill/scripts/validate_source_links.py /path/to/syntax-skill第一个命令检查 Codex skill 的目录结构和 YAML frontmatter；第二个命令检查八个领域是否都包含章节、页码、XHTML 文件、锚点和回读关键词。
本仓库是一个原创的方法论和引用索引层，基于 Edward A. F. Gibson 的《Syntax: A Cognitive Approach》及其原文定位信息构建。仓库不再分发整本受版权保护的英文原书或中文译本。