Doclific 是什么？
Doclific 是一款完全开源、本地优先、AI增强型技术文档工具，它并非传统 Wiki 或静态站点生成器（如 Docusaurus、MkDocs），而是一个嵌入代码仓库的“活文档操作系统”——将文档写作、代码引用、架构可视化、AI协作与CI/CD流程深度耦合，真正实现 “文档即代码”（Docs as Code）的终极实践形态。
其核心哲学是：技术文档不应脱离代码而存在，更不应滞后于代码演进。 Doclific 将文档文件（.md）与源码文件（.ts, .py, .go, .sql 等）置于同一 Git 仓库中，通过智能解析、符号引用与实时同步机制，让每一段文档都具备可验证、可追溯、可执行的工程属性。
官方定位精准概括：
“All your technical documentation — rich text, smart code snippets, ERDs, architecture diagrams, and more — in your codebase. No more scattered docs. No more context switching.”
（所有技术文档——富文本、智能代码片段、实体关系图、架构图等——全部内嵌于你的代码库中。告别文档散落各处，告别频繁上下文切换。）
Doclific 不依赖云端 SaaS 服务，100% 本地运行（基于 Node.js + Electron 架构雏形，当前 CLI + VS Code 插件形态为主），所有文档解析、AI调用（本地或代理）、代码扫描均在开发者本机完成，满足金融、政企、芯片等强合规场景对数据主权与隐私安全的严苛要求。
产品功能
1. Notion-like 智能富文本编辑器
支持 Markdown 原生语法 + 可视化块编辑（标题/列表/表格/引用块/分栏）
内置代码块智能高亮与语言自动识别（支持 200+ 编程语言及配置文件）
支持数学公式（LaTeX）、Mermaid 图表内联渲染、自定义 CSS 注入
2. AI 文档增强引擎（AI Integration）
原生集成 Cursor / Claude AI 助手：一键启用“AI Docs Mode”，在编辑器内直接唤起 AI 进行：
自动补全函数注释（基于函数签名与上下文推断用途）
重写模糊描述为精准技术说明
生成 API 使用示例（自动提取参数类型、返回值、异常分支）
将 commit message 转为变更日志（Changelog）条目
所有 AI 请求默认走本地 Ollama 模型代理（如 codellama:7b, phi3:mini），亦支持 OpenRouter / Anthropic API 密钥配置，无数据上传风险
3. 动态代码片段（Dynamic Code Snippets）——革命性特性
在 Markdown 中使用 {{#include src/utils/db.ts:12-28}} 语法，直接引用源码指定行范围
文档构建时自动提取、高亮、版本锁定（Git SHA 绑定）
支持 {{#include src/api/routes.ts::handleUserLogin}} 按函数名/类名/正则匹配智能定位
文档即快照：每次 git checkout 后，文档自动呈现对应版本的代码实况
4. ERD 实体关系图构建器
内置 SQL 解析器（支持 PostgreSQL / MySQL / SQLite DDL）
输入 CREATE TABLE users (...) 即自动生成可交互 ERD
支持拖拽布局、关系标注（1:1, 1:N, N:M）、主题色定制、导出 PNG/SVG/PDF
5. 白板式架构图（Interactive Whiteboard）
基于 Excalidraw 引擎深度定制
提供云服务图标库（AWS/Azure/GCP）、微服务组件、数据库、消息队列等标准元素
支持双向链接：点击图中 “Auth Service” 可跳转至 /docs/services/auth.md
可嵌入 Markdown：![[arch-diagram.excali]]
6. CI/CD 智能校验与自动修复（Coming Soon）
新增 doclific ci 命令，集成至 GitHub Actions / GitLab CI
扫描所有 {{#include}} 引用，比对当前 HEAD 与文档中记录的代码哈希
发现不一致时：
输出详细差异报告（新增/删除/变更行）
对“仅偏移变化”（如上方插入空行）自动修正行号范围
对语义变更（函数逻辑重写）触发 PR 评论提醒技术负责人审核
产品特色
| 维度 | 传统方案（Confluence/Docusaurus） | Doclific |
|---|---|---|
| 文档位置 | 独立平台或独立 docs/ 目录 | 与 src/ 同级，Git 原子提交 |
| 代码同步 | 手动复制粘贴 → 易过期 | 动态引用 → 永远真实 |
| AI 协作 | 外挂 ChatGPT 窗口 → 上下文割裂 | 编辑器内 AI → 精准感知当前文件 AST |
| 隐私安全 | SaaS 传输代码 → 合规风险 | 纯本地运行 → 代码永不离境 |
| 维护成本 | 文档更新 = 额外任务 → 常被忽略 | CI 自动告警 → 文档成为质量门禁 |
三大不可替代性总结：
Context-Awareness（上下文感知力）：AI 不再“猜”，而是读取 AST、TypeScript 类型定义、JSDoc 注释、Git blame 历史，生成带证据链的技术描述。
Version-Bound Integrity（版本绑定完整性）：每段文档自带 git commit hash 元数据，git bisect 时可同步回溯文档状态。
Developer-Native Workflow（开发者原生工作流）：无需学习新 UI，VS Code 插件 + CLI + Git Hook 全覆盖，文档修改即 git add && git commit。
使用方法
步骤 1：环境准备
已安装 Node.js ≥ 18.x 与 npm
推荐 VS Code（安装官方 Doclific Extension）
步骤 2：一键安装
curl -fsSL https://raw.githubusercontent.com/muellerluke/doclific/main/scripts/install.sh | bash
脚本自动完成：CLI 安装、VS Code 插件注册、基础模板初始化（docs/README.md, docs/architecture/）
步骤 3：创建首个智能文档
在项目根目录新建 docs/guide-auth.md
输入：
## 用户认证流程 核心逻辑位于 `auth.service.ts`： {{#include src/services/auth.service.ts::authenticateUser}}保存后，插件自动高亮并渲染该函数代码（含类型提示与 JSDoc）
按 Ctrl+Shift+P → 输入 Doclific: Ask AI → 提问：“用中文解释此函数如何防范暴力破解？” → 获取精准回答
步骤 4：启用 AI（可选）
安装 Ollama：brew install ollama（Mac）或官网下载
拉取模型：ollama pull codellama:7b
VS Code 设置中开启 doclific.ai.enabled: true，选择本地模型
适合人群
| 角色 | 痛点 | Doclific 解决方案 |
|---|---|---|
| 前端/后端工程师 | 写完接口忘写文档；Swagger 与代码不一致 | 动态引用 + AI 补全，文档随代码提交自动就绪 |
| SRE / 平台工程师 | 架构图半年未更新，故障复盘无依据 | 白板图存 Git + 双向链接，每次架构评审即提交新版本 |
| 技术文档工程师（TDE） | 80% 时间找代码位置，20% 写文档 | {{#include}} 语法 + 函数名定位，秒级获取上下文 |
| 开源项目 Maintainer | 贡献者看不懂内部设计，PR 常因文档缺失被拒 | CI 自动检查文档覆盖率，新人 PR 必含 docs/ 变更 |
| 金融科技/医疗IT 团队 | 文档需审计留痕，禁止上传第三方 | 100% 本地运行，Git 日志即完整审计轨迹 |
常见问题解答（FAQ）
Q1：Doclific 会把我的代码上传到云端吗？
→ 绝对不会。 所有代码解析、AI 推理（除非显式配置远程 API）、文档生成均在本地完成。网络请求仅用于下载模型（Ollama）或可选的 CI 状态回调（可关闭）。
Q2：支持哪些编程语言的代码引用？
→ 支持所有可通过 tree-sitter 解析的语言（TS/JS/Python/Go/Rust/Java/C++/SQL/YAML/TOML 等），并持续扩展。非结构化文件（如 JSON 示例）也支持行范围引用。
Q3：能否与现有文档网站（如 Docusaurus）共存？
→ 完全兼容。Doclific 生成标准 Markdown，可作为 Docusaurus 的 docs/ 源目录；其 CLI 也提供 doclific export --format html 生成静态站。
Q4：AI 生成内容是否可靠？是否需人工审核？
→ Doclific 的 AI 定位是 “增强工程师，而非替代工程师”。所有 AI 输出均标注来源（如“基于 src/db/query.ts 第 45 行推断”），且强制要求用户确认后插入。我们建议：AI 写初稿，工程师做终审。
Q5：未来是否会闭源？
→ 官方明确承诺：核心编辑器、CLI、VS Code 插件、动态引用引擎将永久 MIT 开源。商业模块仅围绕企业治理、审计、集成等非核心场景。
总结
Doclific 不止是一款工具，它是开发者文档主权运动的基础设施。当行业还在争论“要不要写文档”时，Doclific 已用工程化手段消解了这个问题——写文档不再是额外负担，而是编码行为的自然延伸。
它用“动态引用”终结了文档与代码的割裂，用“本地 AI”捍卫了数据主权，用“CI 校验”将文档提升为质量红线。对于追求极致工程效能的团队，Doclific 不是选项，而是必然。
