iii：让 AI 持续完成
功能迭代与文档维护

从 Vibe Coding 的角度看，iii 值得学习的地方是把一次自然语言需求，逐步收敛成接口契约、局部代码改动和可观察结果。它自身提供统一的 Worker、Function、Trigger 模型；仓库同时维护供开发者和 AI 使用的知识。两者共同减少模型每轮重新猜测系统结构的成本。

依据：[S01] [S02] [S03] [S08] [S20] [S24] [S25] [S27]

阅读边界

分析基于 main@01b15b77f2ae 的目录、关键源码、工作流，以及四个已合并 PR 的正文和文件差异。核对日期为 2026-09-15。文档导航标记 Latest 为 0.23.x、Next 为 0.24.x；这只是文档标签，不能直接当成每个二进制和 SDK 的发布版本。[S04] [S32]

这里没有运行 iii 全套产品测试，也没有复现作者的私有开发会话。后面的模拟不会被描述成作者实际使用过的提示词、内部流程或已上线能力。

iii 是一个以 Rust 引擎为核心的后端组合运行系统。Worker 连接引擎，注册可调用的 Function，再声明什么事件通过 Trigger 触发函数。HTTP、队列、状态、定时任务等能力可以由不同 Worker 提供；开发者、CLI、控制台和 Agent 使用共同的功能调用面。[S01]

必须区分仓库内部与生态能力

当前 README 将 HTTP、cron、queue、state、pubsub、bridge 描述为独立 Compose Worker，来源在 iii-hq/workers；引擎自有的配置、管理和部分基础能力留在 iii 仓库。分析某个 Worker 的完整行为时，必须继续读取其对应版本的实现与文档。仅阅读当前仓库，不能推定所有生态组件的实现细节。[S01] [S03]

功能开发有两个不同场景：修改 iii 平台本身，要读 Rust 实现、SDK 协议、内部测试和 tech-specs；使用 iii 开发应用，重点是相关 Worker 的技能、函数契约和业务代码。后者通常不需要把整个引擎源码放入模型上下文。

下面是与本次主题最相关的迭代样本，不代表完整发布史。设计文档日期、PR 合并时间和正式发布状态分别记录。

把 #2146 还原成一个可学习的开发切面

PR 报告 iii-compose 测试 391 通过、1 忽略；这是作者记录的验证结果，并非本次分析重新执行的结果。[S19] [S25]

这里的“产品文档”包含不同生命周期的知识。混在同一个上下文窗口里，AI 容易把草案、已实现行为和历史兼容策略同时当成当前事实。

目录与职责依据：[S01] [S02] [S03] [S04] [S10] [S17] [S20] [S25]

文档分类用来降低检索歧义

.cursor/rules/docs.mdc 按路径匹配 docs/**/*.mdx 与 docs/**/*.md，声明 alwaysApply: false。它先把任务归入教程、操作指南、参考、原理说明，再指向对应写作 Skill。全局写作规则鼓励通过链接引用已有概念，避免在每份文档里重复维护相同知识。[S05] [S06]

这些规则描述的是仓库中的文档工作流。它们不会自动替代用户要求，也不能保证每个 AI 工具都识别 Cursor 的匹配机制。

第一层：稳定规则，让模型知道怎么参与

AGENTS.md 给出构建和测试命令、目录地图、函数 ID 使用 ::、HTTP 路径带前导斜杠、cron 字段使用 expression 等约束。它还要求 Skill 具备用途与边界部分。这类高复用规则适合常驻入口。功能细节应由入口链接到专门文件，避免入口无限膨胀。[S02]

第二层：能力知识，让模型知道可以复用什么

当前顶层目录是 6 个 iii 核心知识 Skills，加一个 presentation 工具。Worker 专有能力知识尽量留在 Worker 文档，减少同一队列、状态或 pubsub 用法在多个目录中重复维护。引擎 Worker 的发布载荷生成器还接收版本参数，并把选中的 Skill 内容作为发布数据。[S03] [S16]

第三层：任务上下文，让模型知道这轮改什么

Linkly 每章提示词指定函数名、文件位置、数据约定和预期结果；并行工作前先约定 topic 或 payload，最后由主任务集成。在这一层，最重要的是明确继承哪些行为、改变哪些行为、必须通过哪些验收。[S20]

第四层：代码与运行证据，让模型校正理解

当描述与实现不一致时，应定位目标版本的实现、测试和 PR。例如 Compose 的 schema 查询可以暴露请求响应结构，Console 与 trace 可以观察真实调用。检索得到的说明负责导航，执行证据负责验证具体假设。[S18] [S20] [S25]

网站生成器明确从构建后的首页、固定 overview、博客索引和 appendix 生成两个公开文件。它不是扫描整个代码库后生成所有事实的知识引擎。[S15]

一份更可靠的读取顺序（实践建议）

1. 锁定目标代码提交、产品版本和依赖版本。
2. 读取适用的仓库入口与当前任务契约。
3. 按修改路径加载必要的模块说明、Skill、接口参考。
4. 检索对应实现、调用者和回归测试；形成影响范围。
5. 出现冲突时记录冲突，按任务目标澄清期望，再通过测试确认实际行为。
6. 每完成一个可验收切片，将决定、验证和剩余工作写回任务记录。

这是一套基于仓库机制整理的操作建议，不是声称 iii 已经实现了统一的自动上下文调度器。

最值得复用的是编辑源内容，再生成多个消费入口。不要让“给人看的文档”和“给 AI 的文档”独立演化成两套事实。

1. MDX → 对应的 .skill.md

.skill-check.yaml 采用 version: 2、mode: docs，匹配 docs/next/**/*.md 和 docs/next/**/*.mdx，排除该路径下的 changelog 与 Linkly 测试工作区。单页转换生成同目录的 <source>.skill.md。例如教程源与产物分别为 agentic.mdx、agentic.mdx.skill.md。[S07] [S20] [S21] [S29]

# 已安装项目使用的 render/check 工具后，在仓库根目录执行
iii-skill-render --write docs/next/tutorials/linkly/agentic.mdx
iii-skill-check verify-rendered docs/next

# 然后同时查看源文档和派生文件的 diff
git diff -- docs/next/tutorials/linkly/agentic.mdx docs/next/tutorials/linkly/agentic.mdx.skill.md

产物首行明确说明由生成器产生，并指回编辑源。转换主要解决同源输出，不保证 token 压缩：本次读取的 Linkly Skill 仍保留大量 provider 选择界面的 JSX。不能仅凭扩展名就认定内容已经适合小上下文模型。[S21]

2. 校验 → PR 反馈

主工作流设置 write: false、scope: pr-diff：常规运行负责校验与报告，不自动替开发者提交。外部 Action 包含结构、Vale 和 AI 三层；没有 AI key 时会跳过 AI 层并警告。该版本的 Action 对本 PR 范围内的生成漂移报错，对范围外已有漂移给出警告。另一个 workflow 允许有权限的维护者通过指定评论复选框触发重新生成。[S08] [S09] [S29] [S30]

这些检查能发现结构、文风和源文件与产物不一致；无法替代 API 调用测试、数据迁移测试和业务验收。也不能仅凭 workflow 文件存在就声称它是仓库分支保护中必需通过的检查。

3. 源码 → SDK / CLI 参考

SDK 流程使用 TypeDoc、griffe 与 rustdoc JSON 提取资料，再生成 docs/next/reference/sdk-*.mdx 和 helpers-*.mdx。CLI 文档由命令定义生成，主 CI 重建后检查提交的 CLI reference 是否过期。API 工作流在 main 相关源文件变动后运行，不等于所有 API 文档都在 PR 合并前完成一致性验证。[S12] [S13] [S14]

4. Next → Latest → 历史版本

稳定 minor / major 发布会归档旧 Latest，并把 Next 复制到根目录；patch 更新根目录内容，不新增归档、不提升 Next 标签；预发布不轮转文档。源码、Next、Latest 和安装版本因此可能处于不同阶段。AI 开发前必须先选版本，再选材料。[S10] [S11]

建议使用“闭环记录”，而不是复制整段聊天

偏差：无参数执行导入客户端时退出并打印 Usage。
原因：任务只要求支持 CSV，没有定义默认文件。
决策：CSV 路径为可选参数；默认 test.csv。
影响：客户端、教程命令、测试夹具、AI Skill。
验收：不传参数仍可运行；显式路径仍被支持；读不到文件时明确报错。
持久化：修改源说明 → 重新生成 → 核对 diff → 记录验证结果。

仓库已有 Linkly 的 Agentic 路径：每章提供一段任务提示，让 Agent 修改 Worker，再由使用者通过控制台、CLI 或客户端检查结果。下方“功能增量、契约、验收”提炼自教程；“建议写回”是为了跨会话开发补充的管理动作。[S20]

为什么分轮开发有效

每一轮都让系统保留可运行状态，再增加一项能力。数据从状态存储发展到数据库，点击处理从同步调用发展到异步队列，再扩展到实时流与浏览器。模型只需处理这轮的增量、既有契约和回归条件，不需要重新设计所有组件。

教程也展示了并行任务：先约定共享 topic 或 payload，再划分文件和目录，最后集成。第一章虽然最终合并到同一 link/src/index.ts，但提示词要求主任务负责合并；在实际团队中仍应安排单一文件写入者或隔离分支，避免覆盖。

_workspace/run.sh 会从模板创建临时项目、按章节启用代码并执行断言，依赖外部 templates checkout。它体现了教程可执行化，但它测试的是模板章节路径，不能直接推断为对所有自由生成结果做了自动评测。[S22]

假设 Linkly 已完成第 3 轮，具备数据库和缓存。用户提出：“活动短链可以设置失效时间，过期后不要继续跳转，旧链接仍然可用。”这个功能能同时检验需求上下文、接口、存储、缓存、测试以及会话恢复。

轮次 A：把需求改写为可验证契约

先固定行为：新增可选 expires_at，只接受带时区的 ISO 8601 时间，内部归一化 UTC；字段缺省或 null 代表永不过期；设置值必须晚于当前时间；解析时满足 now >= expires_at 即失效。对外 HTTP 跳转统一返回 404，以保留“不可解析”的简单语义；是否需要 410 是另一项产品选择，不能由模型自行决定。

旧 link::resolve 的输出继续保持 {url} 或 {url:null}；新字段放在内部数据记录以及创建接口的输入中。数据库 links 增加可空字段；迁移必须保留已有数据。这里的 SQL 列类型与迁移实现应在读取现有 schema 后确定。

轮次 B：整理本次需要的上下文

本轮通常不需要整个引擎源码、全部 SDK、其他产品的历史归档或前端第 7 章。若项目已经完成全部七章，则必须扩展范围：CSV 导入、更新接口和前端表单都要明确是否支持该字段。

轮次 C：先定位影响，再实施最小切片

1. 检查 schema 与数据初始化逻辑，加入可重跑的迁移，旧行保留 null。
2. 创建路径校验时间；数据库记录与缓存记录都携带过期信息。
3. 解析路径对缓存命中和数据库回源使用同一套过期判定。
4. HTTP handler 保持既定输出；过期短链与不存在短链均返回 404。
5. 如果存在更新路径，明确“未传字段保持原值，null 清除过期时间”的额外契约后再实现；不要让这部分隐含混入首个切片。

最常见漏项是只在数据库查询时过滤过期时间，导致缓存命中仍然跳转。缓存里的数据也必须经过相同业务判定；缓存 TTL 可以优化，不能替代正确性条件。

轮次 D：用验收矩阵替代“看起来能用”

测试使用可注入时钟或现有测试框架的时钟替身，避免真实等待与时间临界点抖动。这里列的是模拟任务应执行的测试，不是已运行结果。

轮次 E：同一功能完成时写回哪些文件

源代码与测试进入同一变更；更新创建与解析的参考说明、迁移说明和受影响的教程。如果开发的是 iii 仓库文档，编辑 Next 后重新生成对应 Skill；如果开发的是自己的 Linkly 应用，使用自己项目的文档生成规则。不要把应用 PRD 写进上游 iii 仓库的产品文档。

轮次 F：新会话接手，不重新猜测

假设迁移与创建逻辑已完成，缓存测试尚未完成。交接记录必须包含实际提交 SHA、未提交改动、已通过和未执行的测试、最后一个失败、下一步命令。新会话先验证记录对应的代码状态，再做缓存边界测试。聊天摘要负责导航，spec 和代码负责精确事实。

下列文件是建议为自己的项目补充的最小组织方式；它们不代表 iii 已经存在相同目录。重点是每份文件只承担一种职责。小改动可合并在一个任务文件里，不必为了形式创建很多空文档。

# LINK-EXPIRY 上下文清单

## 基线
base_commit: <实际读取 git rev-parse HEAD 后填入>
target_release: <应用版本>
worker_versions: <锁文件中的实际版本>
status: planned

## 本轮目标
让短链支持可选过期时间，保留旧链接与原 resolve 输出。

## 权威材料
- 行为与验收：docs/features/link-expiry/spec.md
- 当前实现：link/src/index.ts
- 现有 schema / 测试：<定位后填写真实路径>
- Worker 能力：<数据库与 state 的版本化资料>

## 读取范围
必须：上述材料 + 适用 AGENTS.md。
按需：创建、解析、缓存、HTTP 的调用者和测试。
本轮不加载：无关引擎模块、所有历史归档。

## 冲突处理
列出“目标契约 / 代码实际行为 / 文档说法”的差异。
不要自行把草案或旧版本描述提升为当前事实。

## 输出
改动文件、验收编号与结果、剩余风险、下一步。

# LINK-EXPIRY 功能契约
status: accepted
owner: <负责人>
last_verified_commit: <实际 SHA 或 unknown>

## 目标
活动链接到期后不可继续跳转；旧链接保持可用。

## 接口
create 输入新增 expires_at?: string | null。
string 必须为带时区的 ISO 8601，归一化 UTC，晚于当前时间。
resolve 输出保持 {url} 或 {url:null}。
到期边界为 now >= expires_at；HTTP 返回 404。

## 数据与兼容
links 增加可空字段；旧行与旧缓存缺省视为永不过期。
缓存记录保留 expires_at；每次 resolve 都判断是否过期。
迁移可重复执行，不清空已有数据。

## 非目标
本切片不实现自动物理删除、不增加按用户时区的输入界面。
如需支持修改过期时间，另行明确更新接口语义。

## 验收
AC-01 旧链接可用。
AC-02 未来时间可跳转。
AC-03 恰好到期不可跳转。
AC-04 缓存命中不能绕过过期判定。
AC-05 非法时间拒绝。
AC-06 迁移可重跑、重启后数据保留。
AC-07 原有短码重复处理不退化。

实现 LINK-EXPIRY 的第二个切片：创建与解析路径。

先读取：
1. 适用的 AGENTS.md；
2. docs/features/link-expiry/spec.md；
3. plan.md 与 handoff.md；
4. link/src/index.ts、现有测试与实际 schema。

先报告你定位到的入口、影响范围和契约冲突，再完成实现。
如果所需数据库或 state 调用尚未确认，读取对应版本资料，
不要根据其他语言 SDK 或旧教程猜方法名。

保持 resolve 的原输出；缓存命中和数据库回源都检查过期。
覆盖 AC-01 至 AC-07 中本切片涉及的用例。
遵循项目已有错误模型与测试框架，不引入无关重构。

完成后：
- 汇总实际修改的文件；
- 逐项记录执行过的命令、结果和未执行项；
- 更新 plan.md、handoff.md 和受影响的源文档；
- 有派生产物时重新生成，核对与源文件一致。
没有实际执行的测试不得写成通过。

# LINK-EXPIRY 交接
updated_at: <时间>
branch: <实际分支>
head_commit: <实际 SHA>
working_tree: <干净 / 实际未提交文件列表>

## 已接受决定
- expires_at 缺省为永不过期。
- now >= expires_at 失效；外部返回 404。
- 缓存和数据库读取都执行同一判定。

## 已完成
<填写实际任务、文件与提交；不要复制计划当完成记录>

## 验证
<命令> -> <通过 / 失败 / 未运行>，对应 AC-xx。

## 未完成与阻塞
<例如：缓存热数据跨越失效点的测试尚未完成>

## 下一步
1. 校验当前 HEAD / working tree 与记录相符。
2. 阅读 spec 和相关 diff。
3. 执行或补齐明确的下一项测试。

## 必要证据
<PR、失败日志的精简定位、有效 trace_id；不写入密钥>

模板里的版本号、SHA 和验证结果都必须由执行者读取真实环境后填写。摘要要保留决定、约束和定位信息，详细日志用路径引用；不要把完整聊天无限追加进 AGENTS.md。

按信息类型选择维护方式

每类修改对应哪些文档

建议加到自己的完成条件

• 每条验收均有实际结果，未执行项明确标记。
• 实现、调用者与测试使用同一字段名、默认值和错误语义。
• 人工资料只编辑权威源；生成产物已刷新。
• Next、稳定版和归档的修改范围符合版本策略。
• PR 写清为什么改、行为怎样变、如何验证。
• 长期规则进入入口或决策文件；临时进度留在任务记录。
• 完成后任务标记结束，取消过时的未完成提示。

iii 的实际证据覆盖了同 PR 更新、生成一致性、文档分类与发布轮转；上面的任务状态和验收编号机制是建议补强的部分。[S08] [S10] [S12] [S14] [S25] [S26]

这个仓库已具备很好的工程化基础，但公开材料也暴露出上下文漂移。使用它的经验时，应该同时借鉴它的机制和失败样本。

对应证据：[S02] [S03] [S07] [S10] [S12] [S13] [S14] [S17] [S20] [S21]

不要混淆两类“上下文管理”

开发文档上下文解决项目事实放哪里、何时加载、谁更新、哪个版本有效。模型运行期上下文解决当前调用装得下多少消息、哪些输出裁剪、如何摘要旧历史。

tech-specs/2026-06-08-agentic/context-manager.md 描述后者：assemble 按计数、裁剪、压缩的顺序整理消息；强调工具调用与结果成对保留；会话持久化由调用者负责。该文件是设计材料，本次没有核对外部 Worker 的完整实现，不能宣称它已经自动完成开发文档检索或跨会话任务恢复。[S24]

对于已经有 Java 项目和线上 Agent 的团队，可以先迁移这套文档管理方法。它不要求先迁移语言、框架或业务运行架构。

最小上下文组合

项目入口 + 功能契约 + 相关模块知识 + 目标代码与测试 + 最近交接。优先保证这五部分准确，再扩大知识库。RAG、向量检索和自动摘要可以作为规模变大后的手段；这个仓库样本并不能证明它们是启动阶段的必需条件。

衡量有没有改善

• 恢复成本：新会话找到正确文件和下一步需要多长时间。
• 契约返工：字段、默认值、表名、事件名不一致导致的返工次数。
• 文档漂移：已改实现但尚未更新源文档或派生产物的数量。
• 验收真实性：完成记录中有多少条具备实际执行证据。

这些指标是建议的内部观察方式，没有假设 iii 团队已经采用，也没有虚构效率提升比例。

仓库文件链接固定到本次读取的提交；PR 链接用于查看真实讨论与差异。外部文档转换工具读取的是 v0.4 标签，该标签可能移动。技术建议与模拟内容已在对应章节标明。

建议先读 S02、S03、S20 理解 AI 怎样获得知识；再读 S27、S28 理解提示词为什么也需要迭代；最后看 S08、S10、S25，理解生成、发布和功能 PR 如何衔接。