Docsy - Agent-Native 技术文档平台

Docsy 是一个面向 AI Agent 的 Markdown 技术文档平台：受 ARA（Agent-Native Research Artifact）Protocol 启发，把知识从「人类可读的静态文档」重构为「AI 智能体可解析、可校验、可执行的研究包」。平台以语料库管理为基础层，围绕 规范 → 校验 → 双轨渲染 → 执行推演 → 对外发布 → 运营反馈 的主线，让同一份文档既服务人类阅读，也服务 Agent 执行。

五大能力板块：

板块	能力
语料库仓库管理	多仓库注册（只读挂载）/ 跨库 BM25 检索 / 健康检查与知识图谱 / 段落模式编辑 / 导入中心（docx·html·pdf·txt·QA CSV·URL 抓取）
Agent-Native 文档	AND v1 四层结构 / 14 条 Linter + 健康评分 / 双轨渲染 / 执行推演（Dry-Run 计划 + 只读白名单真实执行 + 变更审批门 + 审计）
AI 应用与自动化	应用中心（可配置对话应用 + 上下文组装）/ 工作流引擎（llm·branch·template·tool·writeback）/ 4K 知识加工流水线 / 仓库级 AI 智能体
发布与集成	MCP Server（外部 Agent 调用检索与执行推演）/ 公开问答页 / embed.js 浮窗嵌入 / 对外 API（Bearer token）/ 运营闭环（日志·评分·标注回流·统计）
平台底座	SQLite 持久层 / 账号体系与鉴权闸门 / Key 服务端加密保险库 / LLM 多供应商代理 / 备份恢复 / Docker 部署

定位：MaxKB 是「知识入库→检索→问答」的消费端平台，Docsy 是「文档治理→校验→执行」的生产端平台——除向量检索（RAG，战略排除）外已对齐 MaxKB 主线能力，独有文档治理与执行推演。详见 docs/MAXBK_GAP_ANALYSIS.md。

旧版「阿里云工单运维文档管理平台」的全部功能已归档至 plugins/aliyun-ops-docs/，未来以插件化方式针对特定赛道独立演进。

功能特性

仓库管理（本地后端驱动）

仓库注册表：注册任意本地 Markdown 目录为语料库仓库（server/registry.ts，持久化于 .docsy/repos.json），支持任意路径、自定义名称、去重校验
只读语料库：共享/外部知识库（如 kudig-database、ai-guru-database）可标记为只读挂载——界面显示只读徽标、隐藏编辑入口，后端对写入请求返回 403，防止误改原始语料
仓库总览：文件数 / 体积 / git 分支与未提交变更 / 健康评分卡片，多仓库一键聚合统计
文件浏览：文件树 + Markdown 渲染，支持行内编辑并写回磁盘（仅限 .md/.markdown，路径穿越防护）
健康检查：复用 corpus-lint 的 generateHealthReport（断链 / 孤立页 / frontmatter 缺失 / 空页 / 重名），给出 0-100 评分与逐条问题清单
知识图谱：基于 [[wikilink]] 构建仓库级图谱，点击节点跳转文件；由服务端构建，超大仓库自动截断并提示
跨库检索：BM25 全文检索（复用 src/lib/corpus-search.ts 的 rankPages），跨全部仓库聚合、相关度排序；服务端并发读盘 + mtime 缓存，二次检索显著提速（详见「大仓库与性能设计」）

Agent-Native 文档

受 ARA Protocol（Agent-Native Research Artifact，密歇根大学等 2026 提出）启发：文档不再是纯叙述，而是 Agent 可解析、可校验、可执行的结构化产物。方法论详见 docs/AGENT_NATIVE_METHODOLOGY.md。

AND v1 格式：同源 .md 文件四层结构——frontmatter（Metadata：服务归属/依赖/SLA/环境绑定）、语义锚点 （Narrative）、标注代码块 ```agent（Executable：动作/断言/错误恢复/超时/回滚）、环境快照（Environment）；自研 YAML 子集解析，零新增依赖
Linter 规则集：14 条规则覆盖元数据缺失、可执行块要素（id/断言/错误处理/超时）、变更动作回滚引用、锚点-步骤引用一致性、模糊表述（「适当调整/视情况/酌情」等）、未绑定变量、过期文档；0-100 健康评分
双轨渲染：同一文档即时渲染为「人类版」（语义锚点可视化徽章）与「Agent 版 YAML」（可执行清单），前后端复用同一纯函数保证一致
工作台：侧边栏「Agent 文档」入口 → 选择仓库 → 扫描 AND 文档 → 四个 Tab（人类版 / Agent 版 YAML / Linter 报告 / 执行）
执行推演（Phase 2，已交付）：五层变量替换引擎（Env > Svc > Ctx > Param > Runtime）+ Dry-Run 模拟计划（变更/只读分类 + 变量渲染 + 回滚引用）+ 只读命令白名单真实执行（curl/ping/nc），变更类动作永不真实执行；审计日志 JSONL 落盘；执行面板支持变量编辑 → 计划预览 → 审批门 → 执行结果（信任边界三道防线）
AI 转换器（Phase 3，已交付）：K0 规范化转换器（规则抽取基础 frontmatter，无 LLM 时降级为仅规则抽取）；转换预览 → 人工确认 → 写回仓库（只读仓库自动排除）；反馈闭环：执行历史成功率统计注入工作台健康度旁展示

发布渠道

公开问答页 GET /publish/:appId：Express 托管最小可用 HTML（自包含 + 内联样式 / JS），未登录、未启用 public 的应用 → 404
embed.js GET /embed.js?app=：动态生成 IIFE 脚本，向第三方站点注入「对话」浮窗按钮，点击展开 iframe 加载 /publish/:appId（可配置 data-token、data-accent、data-position）
对外 API POST /api/v1/chat：Bearer dt- token + scope chat:app 鉴权，CORS 预检支持，源 Origin 白名单通过 DOCSY_PUBLIC_ORIGINS 环境变量配置（空 = 全部允许 *）；固定窗口限流按凭据分桶（DOCSY_V1_RATE_MAX / DOCSY_V1_RATE_WINDOW_SEC，默认 60 次/60 秒，0 关闭），超限返回 429 + Retry-After
会话 channel：ui（AIChat / AppsView 试聊）/ public（v1 公开页）区分来源，标注一致

运营闭环

Docsy 把对话日志、反馈、标注回流与统计仪表盘统一在 #/ops 入口。运营者日常三条主线：

① 查看对话日志 — 按应用 + channel（ui 内置 / AppsView 试聊 / public 对外 API）+ 时间排序检索历史会话，定位上下文引用来源。
- GET /api/ops/conversations?appId= 跨应用聚合（app 名 / 消息计数 / channel / 内置标记）
- GET /api/ops/messages?convId= 单会话消息（带当前评分与引用）

② 收集反馈 + 标注低分消息 — 助手消息下方 👍/👎 直接入库；负分消息一键转为标注产物回流治理。
- POST /api/ops/messages/:id/rating { rating: 1|-1, comment? }
- POST /api/ops/messages/:id/annotate 三种动作：
- doc-patch — 标注为「对来源文档修订建议」（回写需指定目标 .md 路径，作为小节追加进既有文档）
- qa-pair — 标注为「生成 QA 对」（回写默认追加到仓库 qa/faq.md，同名小节拒绝重复回写）
- 4k-input — 标注为「送 4K 加工」（回写为独立文档 4k-inputs/<标题>.md，带 type/source/created frontmatter）
- GET /api/ops/annotations?status= 待处理标注队列
- POST /api/ops/annotations/:id/resolve { status:'applied'|'dismissed' } 闭环标注生命周期
- POST /api/ops/annotations/:id/apply { repoId, confirm? } 产物自动回写（管理员）：先返回写入计划预览，带 confirm:true 才落盘为目标仓库的 .md（预览/落盘分离，未经确认不触碰磁盘）

③ 看统计仪表盘 — GET /api/ops/stats：总数 + 按应用消息量柱图 + 近 7 天每日会话。指标可解释：会话数来自 conversations、消息数来自 messages、评分来自 feedback、标注状态来自 annotations，与底层表直连便于二次校验。

API Token 与发布渠道（运营者常用）

「系统设置 → 系统设置 → API Key Profiles」为发布渠道生成 chat:app scope 的 dt- Token（前端对话 URL 仅一次性返回明文，复制后即只存 sha256）
「应用中心」编辑应用时勾选 公开访问 才会被 /publish/:appId 与 /api/v1/chat 接受；非公开应用即使携带有效 token 仍返回 404
「运营闭环 → 标注」状态机：open（待处理）→ applied（已回写仓库或流水线消化）/ dismissed（驳回）

应用中心（可配置对话应用）

多 Profile / 温度 / maxTokens 字段；提示词（systemPrompt）模板
上下文源：repo=BM25 topK（以用户消息为检索词，服务端组装并标注来源引用）、file=全文注入（>8k 字符截断并告警）、corpus4k=4K 加工产物（由试聊面板随请求附 extraContext，仅 UI 通道生效、上限 8k，公开渠道不可用）
对话运行时：会话与消息落 SQLite（channel=ui），最近 10 轮历史 + 上下文源 + 当前消息；上游可流式 SSE 或非流式 JSON
试聊面板：新建/编辑应用后即可在页内试用，回复含来源引用列表

工作流引擎

5 类步骤：llm（OpenAI 兼容上游，支持指定 Profile）/ branch（contains/equals/regex 三种条件跳转）/ template（变量渲染）/ tool=docsy_search（跨库检索）/ writeback（写回仓库；只读 403）
变量引用：{{vars.x}} / {{steps.stepId}}；分支目标 idx 之前未执行的步骤标记 skipped，避免他臂步骤被错误触发
运行历史 flow_runs；SSE 进度 /runs/:id/events；失败可一键 retry（从失败步恢复，输出复用）
JSON 校验器（version 1、step 类型、输出变量名、branch 目标存在性等），编辑界面 JSON 实时校验

导入中心（多格式摄入）

文件上传：.md / .docx / .html / .txt / .pdf（文本抽取）→ 转 Markdown 写回仓库，frontmatter 注入导入来源；单文件 ≤ 20MB 可多选
URL 抓取：网页正文转 MD；仅 http/https、SSRF 防护（拒绝内网/环回地址，含 DNS 解析校验）、≤3 跳重定向、15s 超时
QA CSV：question, answer, tags? 表头 ≤ 1000 行 → 生成 type: qa 语料文档
同名冲突策略：重命名（-1 后缀）/ 覆盖 / 跳过；只读仓库自动排除且后端 403
导入历史落库，失败可一键重试；段落模式（RepoView 工具栏）按标题切段预览、单段编辑写回（mtime 防并发覆盖）

语料模式

语料整理与加工的统一切入点。4K 处理是运维语料的一种整理输出方式，与加工产物库同属于「语料模式」板块。

4K 处理：K1 知识提炼 → K2 知识结构化 → K3 知识问答 → K4 知识场景化，链式增强；产出 Obsidian 兼容（frontmatter + [[wikilink]]）Wiki 页面，支持断点续传、单阶段重试、逐页导出 / Vault 打包
写回仓库：4K 产物可直接写入任意可写语料库仓库（指定子目录）；只读仓库自动从写回目标中排除
加工产物库：4K 产物暂存于本地 IndexedDB，支持检索、浏览与导出

仓库级 AI 智能体

对话按仓库维度隔离（全局对话 / 各仓库智能体），自动注入当前浏览文件内容 + 4K 产物库 RAG-lite 上下文
流式输出、对话历史检索、Markdown 导出；Cmd+K 全局命令面板支持仓库/文件搜索与跳转

MCP Server（供外部 AI Agent 接入）

把 Docsy 的跨库检索与 AND 执行推演暴露为标准 MCP 工具（docsy_search / docsy_list_and_docs / docsy_and_lint / docsy_and_plan / docsy_and_exec_readonly / docsy_and_audit），Claude Desktop、Cursor 等客户端可直接调用。

信任边界与工作台一致：计划由服务端构建（客户端无法注入命令）；仅纯只读计划（白名单 curl/ping/nc）可真实执行，含变更动作或变量错误的计划一律拒绝并写审计；每次工具调用落全局审计 .docsy/mcp-audit.jsonl，执行另写仓库审计。

HTTP 传输（随 API 服务启动）：设置 DOCSY_MCP_TOKEN=你的token 后重启服务端，MCP 端点为 http://127.0.0.1:8787/mcp（Authorization: Bearer <token>，未设置 token 时端点关闭）
stdio 传输（本地子进程）：npm run mcp

Claude Desktop 接入示例（claude_desktop_config.json）：

{
  "mcpServers": {
    "docsy": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/docsy"
    }
  }
}

多 API Key Profile（服务端保险库）

多套 Profile：名称 / 模型 / API Key / 端点；Key 经 AES-256-GCM 加密存于服务端 .docsy/master.key 保险库，浏览器不持有明文
内置多服务商模型注册表（DeepSeek / 阿里云百炼 / Kimi / OpenAI / 小米 MiMo），切换模型自动匹配官方兼容端点
首次使用可在系统设置「一键迁移」把浏览器本地保存的历史 Key 迁入服务端；迁移前旧调用经服务端单次转发过渡
所有 LLM 调用（AI 对话 / 4K / K0 / 测试连接）统一经服务端代理 /api/llm/chat（SSE 透传）

平台账号与安全

首启引导创建管理员（scrypt 口令哈希），会话为 HttpOnly cookie；本地数据（账号、Key、审计）全部落盘 .docsy/docsy.db（SQLite WAL）
全局鉴权闸门：仓库注册 / Profile / Token / 备份为管理员能力，其余 API 需登录；/api/health、/api/auth（引导与登录）为公开前缀
闸门只覆盖 /api/（并按小写归一匹配，避免 /API/xxx 绕过）：静态资源、/publish/:appId 公开页、/embed.js 与 /mcp 不经此闸门——生产模式下 SPA 与 API 同源，否则首启引导页打不开；MCP HTTP 通道自带 Bearer DOCSY_MCP_TOKEN 校验
API Token（dt- 前缀，sha256 落库，scope：chat:app / and:exec-read / ops:read），供后续对外 API 与 MCP 使用
运营审计：登录 / Profile 变更 / Token 管理写入 audit_ops 表；GET /api/backup 一键导出 SQLite 快照 + 仓库注册表 ZIP（master.key 不包含，需单独保管）

发布说明

按时间顺序的功能交付（每个里程碑配套单元测试，详见 server/__tests__/ 与 src/lib/__tests__/）。

v1.0 — Agent-Native 文档与执行（MS-1/2/3）

MS-1 MCP Server：stdio 与 Streamable HTTP 双传输；6 个工具（docsy_search / docsy_list_and_docs / docsy_and_lint / docsy_and_plan / docsy_and_exec_readonly / docsy_and_audit）；Bearer DOCSY_MCP_TOKEN 鉴权；三级守卫（变更动作拒绝 / 纯只读计划校验 / 审计 JSONL 落盘）；Claude Desktop 接入示例见 README 接入片段
MS-2 平台内核：better-sqlite3 持久层（WAL + 版本迁移 v1→v2，15 张表覆盖账号 / 会话 / LLM Profile / 应用 / 会话 / 反馈 / 标注 / 导入 / 流程 / 运行 / 审计 / 统计）；master.key + AES-256-GCM Key 保险库；账号体系（scrypt 哈希 + HttpOnly 会话 cookie + 全局鉴权闸门：PUBLIC / 管理员 / 登录三级）；POST /api/llm/chat SSE 透传代理；多 Profile 模型注册表；dt- 前缀 API Token（chat:app / and:exec-read / ops:read）；GET /api/backup + POST /api/backup/restore（schema 校验 + 停机换库 + .bak 时间戳留档）；Dockerfile + docker-compose.yml
MS-3 导入中心：5 种格式转换器（.md 直存 / mammoth+turndown+gfm / pdfjs-dist 文本抽取 / .txt 段落合并 / csv QA 对生成）；POST /api/imports/upload|url|qa-csv + 失败重试（upload 临时文件复用）；SSRF 防护（私网/环回/链路本地拒绝 + DNS 解析校验 + 重定向逐跳复检）；只读仓库导入 403；GET /api/repos/:id/segments?path= + PUT /api/repos/:id/segment（mtime 409 防并发）；冲突策略 rename -1 / overwrite / skip

v1.1 — 应用 + 工作流（MS-4）

MS-4 应用中心：可配置对话应用（systemPrompt / Profile / temperature / maxTokens）；上下文组装（repo=BM25 topK 以用户消息为检索词，服务端 searchCorpus；file=全文注入，>8k 截断并告警）；对话运行时（POST /api/apps/:id/chat SSE / JSON，会话以 channel='ui' 落库，最近 10 轮历史 + 上下文源 + 当前消息）；试聊面板（消息发送 + 引用来源展示）；CRUD + 复制 + ?force=1 删除关联会话
MS-4 工作流引擎：5 种步骤 — llm（OpenAI 兼容上游）/ branch（contains/equals/regex 三种条件跳转 + 合流点追踪，他臂步骤标记 skipped）/ template（{{vars.x}} / {{steps.id}} 变量渲染）/ tool=docsy_search（跨库检索）/ writeback（写回仓库，只读 403）；变量命名空间 vars. 前缀；JSON 校验器；运行历史 flow_runs + SSE 进度 /runs/:id/events；重试从失败步恢复，复用已完成步骤输出
4K 重写为内置 flow 模板留待 v2（spec 文档已记录此偏离）— 4K 保持专用前端实现，原因是 v1 流程类型无法表达 per-page fan-out

v1.2 — 发布 + 运营（MS-5/6）

MS-5 发布渠道：GET /publish/:appId 自包含 HTML 公开页（未登录可访问，应用需启用 config.public=true，否则 404）；GET /embed.js?app= IIFE 脚本注入第三方站点右下角「对话」浮窗按钮 → 展开 iframe 加载 /publish/:appId（可 data-token/data-accent/data-position）；POST /api/v1/chat 对外 API（Bearer dt- token + scope chat:app 鉴权，与 session 解耦）；CORS 预检支持，DOCSY_PUBLIC_ORIGINS 环境变量控制 Origin 白名单（空 = *）；会话以 channel='public' 落库
MS-6 运营闭环：GET /api/ops/conversations 跨应用聚合会话列表；POST /api/ops/messages/:id/rating（{ rating: 1|-1, comment? }，UI 在助手消息下显示 👍/👎）；标注回流（差异化）POST /api/ops/messages/:id/annotate 三种动作 doc-patch（对来源文档修订建议）/ qa-pair（生成 QA 对写入仓库 qa/）/ 4k-input（送 4K 加工），状态机 open → applied/dismissed；GET /api/ops/stats（总数 + 按应用消息量柱图 + 近 7 天每日会话）

v1.3 — 对标补齐（对外限流 / 标注自动回写 / 4K 上下文源）

对外 API 限流：POST /api/v1/chat 挂固定窗口限流，按调用凭据分桶（Bearer token 摘要，未带凭据按 IP），默认 60 次 / 60 秒；DOCSY_V1_RATE_MAX / DOCSY_V1_RATE_WINDOW_SEC 可调，MAX=0 关闭。响应带 X-RateLimit-Limit / X-RateLimit-Remaining / Retry-After，429 同样回 CORS 头（否则浏览器只读到一个网络错误）。限流挂在鉴权之前：否则伪造 token 的洪水请求走 401 早退、额度永不累计。零依赖自研（server/rate-limit.ts），未引入 express-rate-limit
标注产物自动回写：GET /api/ops/annotations 列出待处理标注；POST /api/ops/annotations/:id/apply（管理员）把 qa-pair / doc-patch / 4k-input 落成仓库内 Markdown。预览优先：不带 confirm 只返回计划（目标路径 + 将新增小节 + 写后全文），带 confirm:true 才落盘；沿用仓库写入全部约束（仅 .md、resolveSafePath 防越界、只读仓库 403），doc-patch 未经确认不写磁盘。落库 result_json 并推进 open → applied，审计写 annotation.apply（server/annotation-writeback.ts，DB 迁移 v2）
corpus4k 上下文源：应用可声明 corpus4k 源，由客户端把 4K 加工产物随请求以 extraContext 传入（4K 库在浏览器 IndexedDB，服务端不可读）。仅 UI 通道 POST /api/apps/:id/chat 接受，且仅当应用已保存的配置显式声明该源时生效（否则忽略并告警），注入前按 8000 字符截断；/api/v1/chat 与 config.corpus4k 未声明的应用一律不可用——客户端无法向 prompt 注入任意上下文
生产模式修复：闸门改为仅覆盖 /api/ 并小写归一，Docker 单容器下 SPA 首启引导页、/publish、/embed.js、/mcp 恢复可达（此前静态资源被 401 拦截，镜像起不来可用界面）

关键偏离与待办

4K 流程化重写：v1 流程类型不含循环 / 映射 / 子流程，per-page fan-out 不可表达；4K 保留前端专用实现，登记为后续 flow v2 事项
4K → 应用上下文：原设想服务端直接读 4K 产物库，实际产物在浏览器 IndexedDB，改为 corpus4k 源 + 客户端 extraContext（仅 UI 通道、须配置显式声明、8k 截断）。公开渠道因此不带 4K 上下文
对外限流：未采用 express-rate-limit，改为零依赖进程内固定窗口（server/rate-limit.ts）。单容器无 Redis，多实例部署时限流为各进程独立计数
标注回写与 4K 上下文源已交付（见 v1.3），不再列为待办；仍待办的是 flow v2（循环 / 映射 / 子流程） 与 旧仓库级智能体（AIChat）迁入内置应用 这两项开放式改造
多租户 / SSO / 集群 / HTTPS 终结 / 拖拽画布编排 / 语音（STT/TTS）/ IM 渠道插件 / RBAC 细粒度 / 备份恢复精细调度：均不在本批交付范围，按 MaxKB 对标已对齐核心能力

Docker 部署

docker compose up --build   # http://localhost:8787（首次打开引导创建管理员）

单容器：SQLite 与语料目录通过 volume 挂载（docsy-data:/app/.docsy），语料目录按需挂载后在应用内以容器内路径注册仓库。master.key 首次启动生成于同一 volume，需单独保管（GET /api/backup 不含它）。

对外渠道相关环境变量（docker-compose.yml 已透传，均可缺省）：

变量	默认	作用
`DOCSY_V1_RATE_MAX`	`60`	`/api/v1/chat` 窗口内配额，`0` 关闭限流
`DOCSY_V1_RATE_WINDOW_SEC`	`60`	限流窗口长度（秒）
`DOCSY_PUBLIC_ORIGINS`	空（= `*`）	公开渠道 CORS Origin 白名单，逗号分隔
`DOCSY_MCP_TOKEN`	无	MCP Streamable HTTP 通道 Bearer

大仓库与性能设计

平台针对数万篇规模的超大语料库（如 kudig-database 的 21,000+ 篇）做了专门处理：

能力	机制
lint / 图谱扫描	服务端 `LINT_SCAN_LIMIT = 3000` 上限，超出只扫描前 3000 篇并在响应中标记 `truncated`，前端展示「部分扫描」提示，避免单请求阻塞数分钟
跨库检索	并发批读（限流 64）+ 按文件 mtime 失效的内存缓存：冷缓存 5~11s（中文 bigram 分词更重）、热缓存 4~6s（BM25 全量重算的代价）；前端 15s 超时降级并显示「正在跨库检索…」
文件树	仅保留含 Markdown 的目录，目录在前按名排序，2 万篇仓库约 0.8s 返回
字体加载	Google Fonts 非阻塞加载（`media="print" onload`），字体不可达时回退系统字体栈（PingFang SC / Microsoft YaHei），避免渲染白屏

技术栈

前端：React 18 + TypeScript (strict) + Vite 5 + Tailwind CSS + Zustand（persist v3 迁移）
后端：Node.js + Express（server/，tsx watch 运行，端口 8787，Vite 代理 /api）
Markdown：react-markdown + remark-gfm；图谱：cytoscape / 自研力导向布局；图标：lucide-react
测试：Vitest（前端 + server/__tests__ 纯逻辑单测，覆盖率门禁：lines/functions/statements ≥ 45%、branches ≥ 35%）

快速开始

npm install        # 安装依赖
npm run dev        # 开发模式：vite(5173) + api(8787) 并行启动
npm run build      # 类型检查 + 生产构建
npm run preview    # 预览生产构建

首次打开 http://localhost:5173 会先引导创建管理员账号（数据落 .docsy/）；AI 功能需在「系统设置」配置模型 Profile（见下方 AI 配置）。

也提供便捷脚本：

./scripts/run-dev.sh        # 等同 npm run dev
./scripts/start.sh [port]   # 后台启动（默认 5180，PID 与日志管理于 .docsy-dev.pid/.log）

质量检查

npm test               # 运行全部测试（Vitest）
npm run test:coverage  # 测试 + 覆盖率报告（coverage/）
npm run lint           # ESLint 检查（src + server）
npm run format         # Prettier 格式化（src）

CI（.github/workflows/ci.yml，Node 22）：Lint → Typecheck → Test+Coverage → Build，覆盖报告以 artifact 保留 14 天。

AI 配置

启动后打开应用，首次会引导创建管理员账号
系统设置 → API Key Profiles：新增 Profile 并填写 API Key（存入服务端加密保险库）；浏览器 localStorage 中已有旧 Key 的，在设置页「一键迁移」
也可在 .env.local 提供默认 Key（注意：该方式会打包进前端产物，仅建议本机开发使用，迁移到保险库后请移除）：

VITE_MIMO_API_KEY=tp-xxxxx                  # 小米 MiMo Token Plan（配置后默认模型自动指向 MiMo）
VITE_DEEPSEEK_API_KEY=your-key-here         # 未配置 MiMo 时的默认服务商

⚠️ VITE_ 前缀环境变量会打包进前端产物，请勿在公开部署中携带真实 Key；生产环境一律使用服务端保险库 + 代理。

项目结构

docsy/
├── server/                        # 本地语料库后端（Express, 8787）
│   ├── index.ts                   # API 路由（repos/tree/file/git/search/graph/lint/agent-native）
│   ├── registry.ts                # 仓库注册表（.docsy/repos.json，含 readonly 标记）
│   ├── fs-utils.ts                # 路径安全 / md 白名单 / 忽略目录
│   ├── agent-native.ts            # AND 文档发现（frontmatter 标记扫描）
│   ├── agent-engine.ts            # 白名单只读命令执行器（注入防护 + 超时）
│   ├── agent-audit.ts             # 审计日志 JSONL 落盘（分页查询）
│   ├── repo-files.ts              # 文件树 / 解析缓存 / 并发批读（路由与 MCP 共用）
│   ├── search.ts                  # 跨库 BM25 检索（路由与 MCP 共用）
│   ├── db/                        # SQLite 持久层（.docsy/docsy.db，WAL + 版本迁移）
│   ├── vault.ts                   # Key 保险库（master.key + AES-256-GCM）
│   ├── auth.ts                    # 账号 / 会话 / API Token / 全局鉴权闸门
│   ├── llm-proxy.ts               # Profile 管理（掩码回显）+ /api/llm/chat 代理
│   ├── backup.ts                  # 备份导出/恢复（SQLite 快照 + repos.json → ZIP，schema 校验）
│   ├── segments.ts                # 段落管理（按标题切段 + 单段编辑写回）
│   ├── apps.ts                    # 应用中心（应用 CRUD + 对话运行时 + 上下文组装）
│   ├── flows.ts                   # 工作流引擎（llm/branch/template/tool/writeback）
│   ├── imports/                   # 导入中心（转换器管线 / URL SSRF 安全抓取 / QA CSV）
│   ├── mcp/                       # MCP Server（stdio + Streamable HTTP）
│   │   ├── tools.ts               # 6 个工具 + 只读执行守卫 + 双层审计
│   │   ├── http.ts                # /mcp 挂载（Bearer DOCSY_MCP_TOKEN）
│   │   └── stdio.ts               # stdio 入口（npm run mcp）
│   └── __tests__/                 # 后端纯逻辑单测
├── src/
│   ├── components/
│   │   ├── Sidebar.tsx            # 平台导航（仓库总览 / 语料模式 / 系统设置）+ 仓库列表（只读徽标、git 脏标记）
│   │   ├── LibraryView.tsx        # 仓库总览 + 跨库搜索（大仓库 lint 超时降级）
│   │   ├── RepoView.tsx           # 文件树 / 阅读 / 编辑 / 健康 / 图谱（只读降级）
│   │   ├── FourKView.tsx          # 4K 处理流水线（写回目标过滤只读仓库）
│   │   ├── CorpusView.tsx         # 加工产物库（IndexedDB）
│   │   ├── AgentNativeView.tsx    # Agent-Native 工作台（列表 + 三 Tab 双轨渲染）
│   │   ├── AIChat.tsx             # 仓库级 AI 智能体
│   │   ├── CommandPalette.tsx     # Cmd+K 全局搜索
│   │   ├── Settings.tsx           # 多 API Key Profile 管理
│   │   └── ...（MarkdownContent / KnowledgeGraph / ErrorBoundary 等）
│   ├── lib/
│   │   ├── repo-api.ts            # 前端调用后端唯一入口（fetch 封装）
│   │   ├── agent-format.ts        # AND v1 解析器 + 锚点装饰（server 复用）
│   │   ├── agent-lint.ts          # AND Linter 规则集 + 评分（server 复用）
│   │   ├── agent-render.ts        # Agent 版 YAML 渲染（server 复用）
│   │   ├── agent-engine.ts        # 五层变量解析管道 + Dry-Run 计划生成（server 复用）
│   │   ├── agent-converter.ts     # K0 Agent 化转换器（规则抽取，server 复用）
│   │   ├── agent-store.ts         # 执行历史 IndexedDB（docsy-agent 库）
│   │   ├── agent-native-api.ts    # AND 后端 API 类型化封装（含 plan/exec/audit）
│   │   ├── ai-service.ts          # LLM 客户端（经服务端 /api/llm/chat 代理，浏览器不持有 Key）
│   │   ├── corpus-search.ts       # BM25 检索（server 复用）
│   │   ├── corpus-lint.ts         # 健康检查（server 复用）
│   │   ├── four-k-service.ts      # 4K 流水线核心
│   │   ├── settings-api.ts        # 鉴权 / 服务端 Profile / 迁移 API
│   │   ├── import-api.ts          # 导入中心 / 段落 API
│   │   ├── apps-api.ts            # 应用中心 / 会话 API
│   │   ├── flows-api.ts           # 工作流 API
│   │   ├── ops-api.ts             # 运营闭环 API
│   │   └── useHashRouter.ts       # Hash 路由（#/library|repo|corpus|processing|import|apps|flows|ops|settings）
│   ├── store/index.ts             # Zustand store（persist 迁移；Profile 元数据缓存，Key 在服务端）
│   └── App.tsx / main.tsx
├── plugins/aliyun-ops-docs/       # 归档：阿里云工单运维文档平台（含演示 mock 数据，插件化演进）
├── scripts/                       # run-dev.sh / start.sh 便捷启动脚本
├── docs/                          # 平台转型与评估记录（PLATFORM_PIVOT / GAP_ANALYSIS / PROJECT_EVALUATION 历史存档；MAXBK_GAP_ANALYSIS / MAXBK_PARITY_SPEC 为 MaxKB 对标现行文档 + 交付状态）
├── docs/agent-native-examples/    # AND v1 demo 示例语料（回滚 / 告警 / 磁盘排查）
├── .docsy/repos.json              # 仓库注册表（运行时生成/维护）
└── vite.config.ts / vitest.config.ts / eslint.config.js

路由

Hash	视图
`#/library`	仓库总览
`#/repo/{repoId}/{filePath?}`	仓库浏览（filePath 需 encodeURIComponent，省略时显示仓库概览；工具栏可切换「段落」模式）
`#/corpus`	加工产物库
`#/processing`	4K 处理
`#/agent-native`	Agent-Native 文档工作台
`#/import`	导入中心（文件 / URL / QA CSV）
`#/apps`	应用中心（可配置对话应用 + 试聊）
`#/flows`	工作流引擎（流程编辑 + 运行时间线）
`#/ops`	运营闭环（统计 / 会话日志 / 反馈标注）
`#/settings`	系统设置（Profile / API Token / 备份）

首次访问会先经过登录闸门（#/ 任意路由）：首启引导创建管理员，之后正常登录。公开问答页 /publish/:appId 与浮窗嵌入不经过 SPA 登录。

使用指南

登录：首次启动引导创建管理员账号（数据落 .docsy/，口令 scrypt 哈希）；此后每次访问先登录
注册仓库：侧边栏「+」或总览页「添加仓库」，输入本地 Markdown 语料库绝对路径；共享/外部知识库可勾选只读挂载
跨库检索：总览页顶部搜索框（或 Cmd+K），输入关键词实时检索全部仓库
浏览与编辑：点击仓库 → 文件树选择文件；「编辑」整篇修改回存，「段落」模式按标题切段、逐段编辑（mtime 防并发覆盖；只读仓库隐藏写入口）
健康与图谱：仓库概览页「健康检查」「知识图谱」分析整个仓库（超大仓库自动部分扫描并提示）
AI 问答：右侧面板自动切换为当前仓库的智能体，可引用当前文件内容
4K 处理：语料模式 → 4K 处理，粘贴文档运行 K1-K4 流水线，「写回仓库」将产物落到指定可写语料库
Agent 文档：语料模式 → Agent 文档，选择仓库查看 AND 文档列表；选中文档查看人类版 / Agent 版 YAML / Linter 报告 / 执行四 Tab（demo 语料见 docs/agent-native-examples/，可注册该目录为仓库直接体验）
导入语料：语料模式 → 导入中心，三 Tab（文件上传 / URL 抓取 / QA CSV）选择目标仓库与冲突策略后导入；历史记录失败可一键重试
创建应用：语料模式 → 应用中心，新建应用配置系统 Prompt / 模型 Profile / 上下文源（仓库 BM25 或文件全文），保存后页内「试聊」验证引用来源；勾选「公开访问」即可被发布渠道使用
编排工作流：语料模式 → 工作流，用 JSON 定义 llm / branch / template / tool / writeback 步骤，运行查看步骤时间线，失败可从失败步重试
发布对外：系统设置生成 chat:app scope 的 API Token；用 /embed.js?app=<appId>&...（或直接分发 /publish/<appId> 链接）把对话浮窗嵌入任意站点；CORS 白名单用环境变量 DOCSY_PUBLIC_ORIGINS 控制
运营复盘：语料模式 → 运营闭环，按应用 / channel 查看会话日志，对助手消息 👍/👎 评分并把低分消息标注为 QA 对 / 文档修订 / 4K 输入；统计页看总量与近 7 天趋势