iii：AI 辅助开发、源码演进与文档工程技术学习文档

1. 整体架构：把 AI 变成仓库中的工程角色

iii 的特点不是简单使用 AI 写代码，而是把 AI 能够依赖的上下文、规则、设计信息、验证方式和知识文档放进仓库，使 Agent 能够在代码库内部按照统一规则执行任务。

2. Agent 上下文系统

2.1 AGENTS.md：仓库级开发协议

AGENTS.md 提供项目地图、常用命令和修改边界。它的作用类似“给 AI 工程师的 CONTRIBUTING + Architecture Notes + Guardrails”。

2.2 .cursor/rules：按任务加载规则

.cursor/rules/docs.mdc 对 docs/**/*.mdx 与 docs/**/*.md 生效。它首先要求判断文档类型，然后加载相应 Skill。

这相当于给 AI 增加一个“文档路由器”：先判断任务类型，再执行对应的写作约束。

2.3 Skills：把长 Prompt 变成仓库能力

.cursor/skills/doc_workflow.md 统一规定文档语气、组件、执行流程和四象限之间的边界。产品级 skills/ 则进一步提供可被 Agent 使用的领域知识和实现方式。

3. 功能开发机制

从 Namespace 和 Worker Compose 的真实提交可以看到，iii 的大型功能开发通常由多个工程层共同组成。

3.1 Tech Spec 是设计记忆

tech-specs/ 不只是最终方案说明，还会记录：

• 当前源码中的 load-bearing facts；
• 架构图和生命周期；
• 候选方案与拒绝理由；
• Non-goals；
• Open questions；
• 不同子领域拆分文档。

这使 Agent 在后续迭代时不仅知道“最终怎么做”，还知道“为什么没有选择其他方案”。

3.2 实现由代码、测试、Docs 同时构成

Worker Compose #2034 同时新增 crates/iii-compose、跨平台测试矩阵、engine e2e、Compose 文档和对应的 Agent 文档。这说明对于公共功能，完成定义不是只有源码合并，而是同时完成：

4. 功能迭代机制：实现之后继续进行架构收敛

iii 的功能迭代不是“新增功能后停止”，而是先建立新模型，再逐步让旧机制迁移到新模型。

Namespace → Worker Compose → Legacy Worker Lifecycle Migration 是当前最典型的一条演进链。

5. Namespace：为后续多项目运行建立统一身份模型

2026-08-17 合并的 #1984 将 namespace 引入 engine 和四套 SDK。它不是简单给 function id 加前缀，而是把 namespace 作为独立 routing dimension。

5.1 关键设计

• Function id 保持不变，例如 state::get；
• namespace 独立于 function id；
• Worker 身份使用 (namespace, worker_name)；
• Function ownership、service registry 和 trigger routing 都带 namespace；
• 旧 SDK 不传 namespace 时进入 default；
• Node、Rust、Python、Go SDK 同步支持。

5.2 为什么这个变化重要

在没有 namespace 时，同一个 engine 上很难安全运行多个具有相同 worker 名称的项目。引入 namespace 后：

project-a / namespace=orders
  state::get

project-b / namespace=analytics
  state::get

同一个 function id，可以存在于不同 namespace。

5.3 多轮反馈与验证

#1984 的 PR 记录了多轮外部检查与修复，包括 browser/Python/Go SDK parity、ownership race、late registration 和 namespace inheritance 等问题，并为发现的问题增加针对性测试。

这说明 AI 辅助开发的关键不是要求一次生成正确，而是构建高质量的反馈循环。

6. Worker Compose：从 Tech Spec 到架构迁移的完整案例

6.1 第一阶段：Tech Spec

tech-specs/2026-07-14-worker-compose/ 被拆成多个技术域：

• README.md：总体架构；
• cli-contract.md：CLI 契约；
• compose-file.md：文件 schema；
• configuration.md：配置；
• lifecycle.md：生命周期；
• namespace.md：namespace 模型；
• scripts.md：生命周期脚本。

6.2 第二阶段：新增独立 Compose runtime

#2034 新增独立的 iii-compose crate，而不是直接扩展旧 worker lifecycle。这种方式建立了清晰边界，便于单独测试和快速迭代。

6.3 Compose 本身也是一个 Worker

Compose daemon 注册为普通 worker，并暴露：

compose::up
compose::down
compose::status
compose::logs
compose::list
compose::validate
compose::add
compose::remove
compose::restart
compose::update
compose::schema
compose::stop

这体现 iii 的架构方向：尽量让管理能力本身也使用 iii 自己的 Function / Trigger / Worker 模型，而不是不断增加特殊控制通道。

6.4 第三阶段：迁移旧生命周期

#2074 删除旧的：

• iii worker；
• worker::*；
• 通过 iii.toml 的 engine fallback；
• engine-managed project workers。

项目 worker 改为声明在 worker-compose.yaml 中。这样 Compose 从“新增功能”进一步成为统一的项目生命周期模型。

7. Observability：从轮询和专用 Stream 收敛到 Trigger

Observability 的近期演进展示了 iii 如何持续把内部特例迁移到统一 primitives。

7.1 Trace persistence

#2067 将 trace 持久化到磁盘，并重新设计 observability configuration UI。这让 trace 从短期内存可视化能力变成更适合长期运行的系统能力。

7.2 Trigger-driven invalidation

#2088 移除 trace live streams 和 Console 每秒轮询，改成：

这个模式可以称为 notify-then-query：

• Trigger 只负责“有变化”的通知；
• Query 仍负责真正的数据语义；
• 过滤逻辑继续由 engine 统一维护；
• 空闲时不产生无意义轮询流量。

这类变化对于 AI 友好，因为 Agent 要理解的底层模型越来越统一。

8. RC 发布节奏：代码变化快速进入候选版本

版本 bump commit 由 iii-ci[bot] 完成。可以看到 0.23 采用了较短的候选版本反馈周期，使架构级修改快速进入真实验证阶段。

9. docs/README.md：文档工程总入口

docs/README.md 不是普通目录说明，而是 iii 文档系统的入口文件。它通过 frontmatter 明确标记为 owner: devrel、type: explanation，并直接定义文档源码、预览、API Reference 生成和版本发布之间的关系。

9.1 Docs as Code 的实际流水线

这里形成了一个非常清晰的知识工程结构：源码负责技术事实，MDX 负责人工维护的知识表达，generator 负责自动 Reference，Mintlify 负责面向人的展示，iii-skill-render 负责面向 Agent 的文本投影，RELEASING 负责知识版本生命周期。

9.2 API Reference 为什么要从源码生成

README 明确要求在预览文档前使用 pnpm generate:api-docs 刷新 SDK API Reference。它解决的是 API 文档与代码漂移问题。

对 AI 辅助开发而言，这一点很重要：Agent 修改公共 SDK 后，不应该再手工复制 API 定义到 Reference，而应该让源代码和生成器维护接口事实，从而降低参数、类型和示例过期的概率。

9.3 README.md 与 README.md.skill.md 的单向派生关系

docs/README.md
      │
      │ iii-skill-render
      ▼
docs/README.md.skill.md

# generated file header:
# DO NOT EDIT
# Edit docs/README.md

这明确体现了 One Knowledge Source → Multiple Knowledge Projections：同一份文档知识可以同时生成适合 Web 阅读的人类视图和适合 LLM 读取的 Agent 视图，但只维护一个源文件。

9.4 README 在 AI 辅助开发中的位置

10. Docs 工程体系

10.1 当前版本结构

docs/docs.json 当前明确维护：

这意味着文档不是等 stable release 后才编写，而是在 Next 阶段跟随代码演进。

10.2 文档按用途分类

10.3 Breaking Change 有专门 Migration Guide

Worker 生命周期迁移没有只写一条 Changelog，而是新增完整 how-to，包括：

• 需要备份的文件；
• 旧配置到新配置的映射；
• engine-owned worker 与 project worker 的区别；
• worker-compose.yaml 示例；
• 验证命令；
• 错误码；
• 回滚条件。

这是功能迭代文档管理中很重要的实践：发布说明负责告诉用户“变了什么”，Migration Guide 负责告诉用户“怎么完成迁移”。

11. 面向 Agent 的文档：Human Source → Agent Projection

11.1 `.skill.md` 是文档的机器友好版本

仓库中大量存在：

docs/next/install.mdx
docs/next/install.mdx.skill.md

docs/next/using-iii/compose.mdx
docs/next/using-iii/compose.mdx.skill.md

docs/next/reference/sdk-node.mdx
docs/next/reference/sdk-node.mdx.skill.md

生成文件头部会标记由 iii-skill-render 生成，并提示不要直接编辑，而是修改源 MDX。

11.2 为什么需要两种表示

11.3 Generated Docs 需要降低检查噪音

.coderabbit.yaml 排除了 docs/next/**/*.skill.md，因为它们由相邻 MDX 生成。这样生成物仍可提交到 Git 供 Agent 使用，但自动代码检查不需要重复分析确定性派生内容。

12. 底层工程原理

12.1 iii 的 AI 辅助开发循环

这个循环比单纯的“Prompt → 生成代码”更接近真正的软件工程。

13. 其他项目参考实现方案

13.1 推荐目录

.
├── AGENTS.md
├── .ai/
│   ├── rules/
│   └── skills/
├── specs/
│   └── 2026-08-28-feature/
│       ├── README.md
│       ├── architecture.md
│       └── migration.md
├── docs/
│   ├── next/
│   ├── tutorials/
│   ├── how-to/
│   ├── reference/
│   └── explanation/
├── scripts/
│   ├── render-agent-docs
│   └── validate-specs
└── .github/workflows/
    └── ai-governance.yml

13.2 AGENTS.md 推荐结构

# Project Map
- backend/
- sdk/
- docs/
- specs/

# Commands
- test
- lint
- format
- build

# Always
- follow naming rules
- add tests for behavior changes
- update public docs for public contracts

# Ask First
- public API
- database schema
- wire protocol
- auth model

# Never
- commit secrets
- bypass compatibility rules

13.3 Tech Spec 推荐结构

---
title: Feature Name
date: 2026-08-28
status: design
release_target: next
---

# Problem

# Current Codebase Facts

# Goals

# Non-goals

# Architecture

# Decisions
| Decision | Chosen | Alternatives | Why |

# Code Impact

# API / Contract Impact

# Tests

# Migration / Rollout

# Open Questions

# Source References

13.4 Docs Impact 分类

13.5 推荐 PR 模板

Spec:
Change Type:
Docs Impact: public | internal | none
Behavior Changed:
Tests:
Migration Required:
Agent Docs Regenerated:
Release Target:
Open Risks:

13.6 推荐 CI

1. validate spec frontmatter
2. run unit / integration tests
3. detect public contract changes
4. require docs-impact declaration
5. build docs
6. render agent docs
7. fail on generated-doc drift
8. verify migration guide for breaking changes
9. build release candidate

14. 源码与提交索引

• docs/RELEASING.md — Next / Latest / Archive 发布规则
• docs/README.md.skill.md — Agent 派生文档
• docs/README.md — 文档工程入口
• iii-hq/iii main
• AGENTS.md
• .cursor/rules/docs.mdc
• doc_workflow.md
• tech-specs
• docs
• docs/docs.json
• Understanding iii / Compose
• Using iii / Compose
• Workers to Compose Migration
• .coderabbit.yaml
• PR #1984 Namespace
• PR #1963 Worker Compose Tech Pack
• PR #2034 Worker Compose Daemon
• PR #2074 Worker Lifecycle Migration
• PR #2067 Observability Persistence
• PR #2088 Trigger-driven Trace Updates