# ionet-ai

本仓库是面向 `ionet` 的本地知识库，用来沉淀可解释、可维护、可治理的知识资产与装配规则。

当前定位是 **local-first full-repository knowledge base**：用户通过完整本地 checkout 使用。

## 核心思路

知识库采用三层结构：

- `Knowledge Assets`
  稳定知识资产与候选知识资产。
- `Skill Pack`
  面向任务的 skill 定义、规则装配和输出模式。
- `MCP / CLI`
  基于完整仓库源码目录诊断请求、装配上下文、搜索证据和控制生成边界。

当前设计重点不是“更大的 RAG”，而是“可约束、可解释、可维护”的 ionet 定向知识系统。

## 公开发现入口

公开源码与机器发现入口：

- GitHub 源码：<https://github.com/iohao/ionet-ai>
- Pages 入口：<https://iohao.github.io/ionet-ai/>
- 最小机器入口：<https://iohao.github.io/ionet-ai/llms.txt>
- 完整机器入口：<https://iohao.github.io/ionet-ai/llms-full.txt>
- 结构化地图：<https://iohao.github.io/ionet-ai/ai-index.yaml>
- 结构化规则：<https://iohao.github.io/ionet-ai/ai-rules.yaml>
- Sitemap：<https://iohao.github.io/ionet-ai/sitemap.xml>

爬虫策略与搜索引擎提交说明见
[AI discovery and public indexing](docs/ai-discovery.md)。

## 本地安装

从当前仓库根目录运行：

```bash
bash scripts/install-project.sh --project /path/to/your-project
```

该命令会：

- 为 Codex CLI 复制可见知识源到目标项目 `.codex/skills/ionet-ai/`
- 写入目标项目 `.mcp.json`，供 Claude Code CLI 和其他项目级 MCP client 使用
- 生成 Codex CLI 的目标项目本地启动脚本 `codex-ionet.sh`
- 写入或更新目标项目 `AGENTS.md` 中的 Codex 项目说明托管块
- 写入或更新目标项目 `CLAUDE.md` 中的 Claude Code 项目说明托管块

MCP 默认通过完整仓库运行：

```bash
uv run --project /path/to/ionet-ai --extra mcp ionet-ai serve mcp
```

CLI 示例：

```bash
uv run ionet-ai kb search "FlowContext"
uv run ionet-ai kb verify-upstream --fact artifact-version --coordinate com.iohao.net:run-one
uv run ionet-ai diagnose "generate an ionet Action feature"
uv run ionet-ai assemble "generate an ionet Action feature" --mode Generate
uv run ionet-ai validate-project --project /path/to/your-project
```

如需 MCP 运行时依赖：

```bash
uv sync --extra mcp
```

## 训练来源边界

当前知识库的维护侧训练/蒸馏来源是：

- `ionet-doc`
- `ionet` 源码
- `ionet-examples` 示例

`ionet-doc` 中只有 `docs/` 目录和首页正文属于当前知识库正文来源；其他目录不要用于当前知识库训练、稳定资产蒸馏或生成链路。

这些来源只面向知识库维护者。普通本地使用者只需要当前 `ionet-ai` checkout，不需要持有上述训练来源。

维护者本地 checkout 通过 `source-roots.yaml` 中的源别名和未跟踪的
`.source-roots.local.yaml` 覆盖文件配置。知识资产中的源码锚点应使用
`alias:relative/path` 写法，不写本机绝对路径。

## 目录地图

### 机器入口

- `llms.txt`
  最小机器阅读入口，说明默认读取路径、高频意图、权威来源和禁止推断边界。
- `llms-full.txt`
  面向 AI 搜索与回答引擎的更完整机器阅读地图。
- `ai-index.yaml`
  结构化仓库地图，面向检索、rerank 和 agent 路由。
- `ai-rules.yaml`
  结构化回答边界，说明读取优先级、authority rules、response rules 和 do-not-infer。

### `docs/`

高层设计、公共规范、用户安装与 MCP 启动说明、任务分类、MCP 工具契约和治理文档。

### `rules/`

稳定规则资产，负责回答“必须遵守什么”和“哪些写法明确不允许”。

### `skill-defs/`

任务族定义源。每个 `skill.yaml` 定义装配列表、任务分类、模式和 token budget。

### `checklists/`

仓库级质量控制清单，包括主题覆盖矩阵、高频问题回归和新知识库 bootstrap 清单。

### `references/`

事实锚点层，记录上游核验入口、维护侧来源边界、源码/文档锚点和 starter 证据边界。

`references/` 不替代 `rules/`、`stable/`、`skill-defs/` 或 `candidate/`，也不直接进入生成主链路；它主要用于回答“事实应该从哪里验证”和“某类证据能证明什么”。

### `stable/`

稳定知识资产。只有 `stable/` 与 `rules/` 能进入默认设计/生成主链路。

当前子目录包括：

- `concepts/`
- `conventions/`
- `architecture-decisions/`
- `example-patterns/`
- `code-templates/`
- `checklists/`
- `api-contracts/`
- `anti-patterns/`
- `faq/`
- `source-policies/`

### `candidate/`

候选知识资产目录。

- 可参与搜索、诊断、解释、评审和现有代码修改。
- 不可直接驱动 `Generate`。
- 进入 `stable/` 前必须经过治理与人工复核。

### `assets/`

本地 starter 和示例资产，用于校准项目结构、最小骨架和可复核示例。

### `src/ionet_ai/`

本地 Python/uv CLI 与 MCP runtime。它直接读取当前仓库的机器入口、`docs/`、`rules/`、`stable/`、`candidate/`、`assets/`、`skill-defs/`、`checklists/` 和 `references/`。

## 当前装配顺序

本地运行时遵循：

```text
用户请求
  -> ionet-ai skill
  -> ionet-ai MCP / CLI
  -> 完整仓库可见知识源
  -> 受约束上下文
```

生成主链路仍遵循：

```text
pattern -> template -> generate -> checklist
```

同时受以下约束：

- `stable/` 才能进入生成主链路。
- `candidate/` 不能直接驱动生成。
- `anti-hallucination-rules` 与 `source-scope-rules` 优先级较高。
- 无稳定 pattern 时，应降级到 `Design` 或 `Explain`。

## 推荐阅读顺序

1. [llms.txt](llms.txt)
2. [ai-rules.yaml](ai-rules.yaml)
3. [ai-index.yaml](ai-index.yaml)
4. [docs/architecture-summary.md](docs/architecture-summary.md)
5. [docs/ionet-ai-v1-design.md](docs/ionet-ai-v1-design.md)
6. [docs/asset-metadata-schema.md](docs/asset-metadata-schema.md)
7. [docs/task-taxonomy-map.md](docs/task-taxonomy-map.md)
8. [docs/knowledge-engineering-playbook.md](docs/knowledge-engineering-playbook.md)
9. [docs/mcp-tool-spec.md](docs/mcp-tool-spec.md)
10. [docs/mcp-assembly-validation-scenarios.md](docs/mcp-assembly-validation-scenarios.md)
11. [docs/knowledge-contract-audit.md](docs/knowledge-contract-audit.md)
12. [docs/user-installation.md](docs/user-installation.md)
13. [docs/asset-governance.md](docs/asset-governance.md)
14. [docs/candidate-source-analysis.md](docs/candidate-source-analysis.md)
15. [docs/candidate-promotion-checklist.md](docs/candidate-promotion-checklist.md)

之后再进入：

- [rules](rules)
- [skill-defs](skill-defs)
- [stable](stable)
- [candidate](candidate)
- [checklists](checklists)
- [references](references)

## 校验命令

```bash
PYTHONPATH=src python3 -m ionet_ai kb search "FlowContext" --limit 3
PYTHONPATH=src python3 -m ionet_ai diagnose "generate an ionet Action feature"
PYTHONPATH=src python3 -m ionet_ai assemble "generate an ionet Action feature" --mode Generate
bash scripts/check-mcp-assembly-scenarios.sh
bash scripts/check-rule-contracts.sh
bash scripts/check-one-application-consistency.sh
bash scripts/check-agents-consistency.sh
bash scripts/check-ai-routing-assets.sh
bash scripts/check-candidate-promotion-ledger.sh
bash scripts/check-upstream-verifier.sh
```

`scripts/check-rule-contracts.sh` is the full Markdown knowledge-contract audit:
it checks metadata, skill asset references, rule assembly, source anchors, and
known generated-code drift patterns. Maintainer source checks resolve
`source-roots.yaml` aliases through `.source-roots.local.yaml` or environment
variables such as `IONET_ROOT`.

## 当前完成状态

- 总设计文档、公共对象与任务分类文档已建立。
- 核心规则、pattern、template、checklist、anti-pattern、faq、source-policy 资产已建立。
- `candidate/source-analysis/` 已形成 review-only 候选车道。
- version-sensitive upstream facts 已有 `kb verify-upstream` 窄入口，用于 Maven/Sonatype artifact 与 GitHub release/tag live verification；JDK/Maven requirement 仍保持人工上游文档核验。
- 本地 Python/uv CLI 与 MCP runtime 已作为默认运行入口。
- `skill-defs/` 已包含 10 个任务定义，其中 6 个是核心 Generate/Design/Review 任务规格，4 个覆盖安装、ionet 项目 setup、框架扩展生成与知识工程方法。
- `llms.txt`、`ai-index.yaml`、`ai-rules.yaml`、`checklists/` 与 `references/` 已建立，用于路由、权威边界、覆盖矩阵、回归问题和事实锚点。
- 当前仓库默认只面向本地完整 checkout 使用。

## 下一步方向

- 按 [checklists/internal-maintainer-release-readiness.md](checklists/internal-maintainer-release-readiness.md) 和 [checklists/internal-maintainer-release-progress.md](checklists/internal-maintainer-release-progress.md) 收敛内部维护者发布门槛与执行进度。
- 继续扩充 `stable/` 的窄 pattern/template/checklist 链路。
- 继续把高价值 candidate note 蒸馏到 stable。
- 继续用 `ionet-ai assemble` 压测各任务族的装配结果。
- 保持本地安装路径简单，优先维护完整本地 checkout 安装方式。