1 line
4.7 KiB
JSON
1 line
4.7 KiB
JSON
{"repo": "13927/ai4se", "files": {"README.md": {"05298ff45e5057b7e2c222971384eb3fc4480802": {"t": 1785674438.3826797, "n": 3556, "h": "389a8303faba1a41", "c": "# aise — Executable CodeWiki Agent (prototype)\n\n> 一句话：把大型代码仓库“自动整理成可校验的 Wiki”，让人和 Agent 都能更快理解、定位、改动与验证。\n\n\n\n## 这是什么\n\naise 是一个 **CLI coding agent（原型）**，核心能力是为任意 git 仓库生成/维护一套 **Executable CodeWiki**（落盘到 `docs/codewiki/`）：\n- **L1**：结构化主事实源（可校验）\n- **Views**：导航/证据视图（从入口和文件快速定位）\n- **L2**：语义解释（可选，配合 LLM 生成）\n\n目标：让“读懂一个项目/评估改动影响/生成修改指南”从靠经验变成可回归流程。\n\n## 核心命令\n\n- `aise init`：初始化 `docs/codewiki/` 骨架与 schema\n- `aise scan`：抽取入口/模块/证据视图（可选 LLM 自动划分模块边界）\n- `aise validate`：schema + 规则校验（可做 CI 门禁）\n- `aise fill --use-llm`：生成/补齐 L2，并生成 `HUMAN_OVERVIEW.md`\n- `aise export --strict`：导出 `WIKI.md`，并做 “0 占位” 严格门禁\n- `aise agent`：交互式 REPL（wiki-first；写入需确认）\n- `aise agent-run`：非交互式集成运行（CI 回归）\n\n## 快速开始（本地）\n\n```bash\npython -m pip install -e \".[dev]\"\n\ncd <your-repo>\naise init --command-name app\naise scan\naise validate --mode static --format text\naise export --out docs/codewiki/WIKI.md --strict\n```\n\n## LLM 配置（OpenAI 兼容）\n\n### 方式 A：环境变量（CI/脚本推荐）\n\n```bash\nexport AISE_OPENAI_BASE_URL=\"https://api.openai.com/v1\"\nexport AISE_OPENAI_API_KEY=\"sk-...\"\nexport AISE_OPENAI_MODEL=\"gpt-4.1-mini\"\n```\n\n### 方式 B：本机全局加密存储（开发机推荐）\n\n```bash\nexport AISE_CRED_PASSPHRASE=\"你的本机口令（建议 20+ 位随机）\"\naise auth-set --base-url \"https://api.openai.com/v1\" --api-key \"sk-...\" --model \"gpt-4.1-mini\"\naise auth-status\n```\n\n## 全自动模块划分（LLM 重写 filetree）\n\n在目标仓库根目录 `aise.yml` 打开：\n\n```yaml\nautoPartitionFiletree: true\n```\n\n效果：\n- `aise scan` 会让 LLM **全量重写** `docs/codewiki/views/filetree.json`（模块边界规则）\n- 并据此刷新 `module_files/module_symbols/java_http_routes/entry_graph` 等视图，保证最终产物一致\n\n## 全仓符号索引（函数/全局变量可定位）\n\n`aise scan` 还会生成：\n- `docs/codewiki/views/symbol_index.jsonl`\n- `docs/codewiki/views/symbol_index.summary.json`（统计摘要，便于门禁与回归）\n\n其中每一行是一条 symbol 记录（JSONL），包含：\n- `file + range`（行列范围）\n- `kind`（function/method/class/global_var…）\n- `module`（由 filetree best-match 推导的主归属模块）\n\n## Architecture (high level)\n\n```\nRaw source repo (read-only)\n ├─ source code / build files\n └─ aise.yml (policy/config)\n ↓ scan (compile)\nCodeWiki (generated artifacts)\n ├─ views/ # evidence & navigation (machine-first)\n │ ├─ filetree.json\n │ ├─ module_files.json\n │ ├─ entry_graph.json\n │ └─ symbol_index.jsonl (+ summary.json)\n ├─ L1/ # structured facts (auditable)\n └─ L2/ + HUMAN_OVERVIEW/WIKI.md (optional, LLM-assisted)\n```\n\n## Guarantees (what you can validate)\n\n- **Symbol-level locatability (Java/C++)**: every symbol record carries `file + range` (1-based line/col).\n- **Coverage gate**: `aise validate` reports coverage for source files under `roots` and can enforce it:\n - `strictSymbolCoverage: true` → missing source files become errors\n - `strictSymbolParseErrors: true` → any `parse_error` fallback records become errors\n - `strictSymbolNoSymbols: true` → any `no_symbols` fallback records become errors\n\n## What does “reference-level” mean?\n\nSymbol-level answers: “where is this function/global/class (file + range)?”\n\n**Reference-level** goes one step further: “how is this symbol used?”\nTypical reference edges (with evidence) include:\n- Java: method call edges, type reference edges, DI wiring evidence (already partially covered by `java_http_routes`)\n- C++: include edges, symbol references, and build target link edges (CMake)\n\nIn practice, reference-level is not “full callgraph everywhere” by default; it is a set of **auditable edges** that you can generate\nincrementally (focus on critical entrypoints or changed modules) and validate with `file:range` evidence.\n\n## License\n\nMIT\n"}}}} |