pindoc

Pindoc

为 AI 辅助开发打造、与代码提交关联的团队记忆。 Agent 负责写下可长期保留的记录；人类负责审阅、讨论和引导。

Pindoc 是一套可自托管的项目记忆系统，面向使用 AI 编码 Agent 协作的团队。它将有价值的 Agent 发现转化为结构化成果：决策、调试路径、任务收尾记录、验证笔记以及关联代码的分析。每项成果都限定在某个项目区域内，并关联到提交、文件、URL、资源或其他 Pindoc 成果。

它仍然是那个你不用亲自输入内容的 wiki，但重点并非为了自动化而自动化。Pindoc 会保留 Agent 工作中值得团队成员和未来 Agent 重用的部分。

它为何存在

AI 编码会话效率很高，但团队上下文仍会悄然流失：

• 调试路径随着终端会话结束而消失；
• 每次有新 Agent 加入，都要重新解释同一个决策；
• 有价值的分析留在某位操作者的聊天记录里，没有转化为团队知识；
• wiki、问题跟踪器、PR 和提交消息中不断累积重复文档；
• 在真实项目环境中，发现问题的人未必能立即修改代码；结构化证据有助于团队讨论并做出决策。

Pindoc 将值得保留的 Agent 工作转化为可搜索、与代码关联的团队记忆。下一位团队成员或编码 Agent 可以在编辑之前向 Pindoc 询问哪些内容值得关注。

Pindoc 有何不同

• 协作记忆层：成果面向团队成员和未来的 Agent 编写，而不是作为私人聊天摘要。
• 仅供 Agent 使用的写入界面：Reader UI 用于阅读和审阅；持久化写入通过 Agent 完成。
• 原生 MCP 工作流：pindoc.context_for_task、pindoc.artifact.propose 和 pindoc.task.queue 等工具用于规范 Agent 行为，而非充当精简版 CRUD API。
• 结构化成果：Decision、Analysis、Debug、Flow、Task、TC、Glossary 和领域包类型。
• 与代码关联的记忆：成果可以指向提交、文件、行范围、资源、URL 和其他成果。
• 专为记录有价值的内容而设计：Pindoc 不保存原始聊天记录，只保留对未来有价值的决策、分析、调试路径、验证结果和任务上下文。
• 多项目守护进程：一个 /mcp 端点即可服务多个项目；每次工具调用都会携带 project_slug。
• 优先支持自托管：Docker Compose 可启动 Postgres、pgvector、Pindoc 守护进程和 Reader SPA。

公开演示

只读公开演示是后续计划，并不包含在此 OSS 版本中。在演示发布之前，README、文档和自托管副本是主要的验证依据。希望全面评估 Pindoc 的操作者可以运行 docker compose up -d --build，并检查自己的成果。

后续演示计划保留在公开演示计划中，以便在适合托管实例时推进。

快速开始

前提条件：

• Docker 27+
• 本地内部试用或小团队使用建议配备 2 个 CPU 核心和 4 GB RAM
• 建议预留 5 GB 磁盘空间，用于 Docker 镜像、Postgres 数据和嵌入缓存；全新克隆的轻量使用至少需要 2 GB
• 首次运行时需要出站 HTTPS，以便缓存捆绑的 EmbeddingGemma 模型和运行时
• 仅在主机原生开发时需要 Go 1.25+
• 仅在 Docker 外进行 Web 开发时需要 Node 20.15+ 和 pnpm 10+

默认 Docker 部署路径通过捆绑的 EmbeddingGemma Q4 ONNX 提供程序支持语义搜索，因此无需嵌入侧车。请参阅系统要求，了解最低配置和可选部署配置。

git clone https://github.com/var-gg/pindoc.git
cd pindoc
docker compose up -d --build

要让运行中的守护进程报告准确的源代码版本，请在构建前通过 Compose 构建参数传入当前提交：

export PINDOC_BUILD_COMMIT="$(git rev-parse HEAD)"
docker compose up -d --build

PowerShell 用户可以通过 $env:PINDOC_BUILD_COMMIT = git rev-parse HEAD 设置相同的值。make compose-up 会自动完成此版本标记。

打开 Reader：

http://localhost:5830/

检查数据库记录的迁移是否与镜像中嵌入的迁移一致：

docker compose exec pindoc-server-daemon pindoc-admin schema doctor --json

该命令只读；如果存在未知的已应用迁移、待处理迁移或校验和偏差，则以非零状态码退出。它绝不会自动删除或接受未知的架构更改。

预览并修复未知、过期、失败或使用不同嵌入模型构建的语义索引：

docker compose exec pindoc-server-daemon pindoc-reembed -dry-run -state needs-refresh
docker compose exec pindoc-server-daemon pindoc-reembed -state needs-refresh

Pindoc 会在 artifact_index_state 中记录已索引的版本、标题/正文哈希、模型标识、尝试次数和上次错误。旧分块会在新嵌入全部准备就绪后才被替换。如果提供程序失败，工件写入仍可成功，并将 index_state.status="failed" 和 retryable=true，同时保留最近一次已知正常的分块供搜索。重新嵌入命令会在各工件独立的事务中处理，并在任何重试仍然失败时以非零状态码退出。

在全新实例上，/ 会先询问所有者身份（显示名称和电子邮件），然后跳转到首个项目向导。完成身份设置后，可直接打开项目向导：

http://localhost:5830/projects/new?welcome=1

修复旧版 REST 构建创建的无所有者项目

旧版构建可能会通过 POST /api/projects 创建项目，却没有对应的 project_members 所有者行。升级后，可通过分配已配置的环回所有者来修复受影响的项目：

INSERT INTO project_members (project_id, user_id, role)
SELECT p.id, s.default_loopback_user_id::uuid, 'owner'
FROM projects p
CROSS JOIN server_settings s
WHERE p.slug = '<project-slug>'
  AND s.default_loopback_user_id IS NOT NULL
ON CONFLICT (project_id, user_id) DO UPDATE SET role = 'owner';

连接 MCP 客户端

Docker 守护进程会公开一个账户级 MCP 端点：

{
  "mcpServers": {
    "pindoc": {
      "type": "http",
      "url": "http://127.0.0.1:5830/mcp"
    }
  }
}

URL 中不包含项目范围。Agent 在项目范围的工具调用中传入 project_slug。pindoc.harness.install 生成的工作区会在 PINDOC.md frontmatter 中保存该 slug。pindoc.workspace.detect 会解析当前工作区最可能对应的 slug，但不会修改守护进程全局的 PINDOC_PROJECT 默认值。在多项目 Docker 守护进程中，会话扫描后仍需显式传入检测到的 project_slug。

completeness=draft 表示成熟度/信任状态，而不是未发布的私有草稿。只要可见性设置允许，已接受的 MCP 写入仍会发布并显示在 Reader 中。对于不得出现在普通用户界面的内容，请使用 visibility=private 或审核工作流。

常见工作流

让 Agent 在项目上下文中开始工作：

Use Pindoc context before editing. Find the current project, inspect assigned
Tasks, then implement the next acceptance item.

典型的 MCP 循环：

1. pindoc.workspace.detect
2. pindoc.task.queue
3. pindoc.context_for_task
4. 编写代码或文档
5. pindoc.artifact.propose
6. 更新 Task 的验收和收尾状态

从 Docker Desktop / Windows 上传资源

pindoc.asset.upload(local_path=...) 读取的是 MCP 服务所在主机/容器中的路径， 而不是 Windows 客户端中的路径。对于 Docker Desktop，请先将主机文件复制到 pindoc-server-daemon 容器中：

pwsh -File tools/push-asset.ps1 A:\path\image.png -ProjectSlug survival-manager

脚本会打印 pindoc.asset.upload 的 JSON 输入，其中包含容器本地路径 /tmp/pindoc-asset-upload/...。

要让 Reader 显示内嵌图片，以下两个步骤需分别执行：

1. 在 body_markdown 中加入 ![alt](<asset.blob_url>)；这会控制渲染效果。
2. 调用 pindoc.asset.attach 并设置 role="inline_image"；这会记录修订元数据和证据。

配置

默认的 Docker 路径为单用户且仅限环回访问：

变量	默认值	用途
PINDOC_DAEMON_PORT	5830	Docker Compose 使用的主机端口。
PINDOC_PROJECT	pindoc	未指定范围的读取/配置所用的默认项目。
PINDOC_PUBLIC_BASE_URL	http://127.0.0.1:${PINDOC_DAEMON_PORT}	生成的链接和 OAuth 元数据所用的公共基础 URL。
PINDOC_BIND_ADDR	127.0.0.1:5830	安全意图。非环回值需要 IdP 或明确选择允许公开且未经身份验证的访问。
PINDOC_AUTH_PROVIDERS	empty	为外部请求启用的身份提供商。目前的提供商：github。
PINDOC_ALLOW_PUBLIC_UNAUTHENTICATED	false	明确选择在没有 IdP 的情况下对外开放。仅可在受信任的网络/反向代理后使用。
PINDOC_FORCE_OAUTH_LOCAL	false	开发标志：通过 OAuth Bearer 身份验证路由环回 /mcp 调用，以便进行本地 QA。
PINDOC_ALLOWED_ORIGINS	empty	以逗号分隔的 CORS 允许列表。为空表示仅允许同源；跨源前端需设置明确的来源。
PINDOC_DEV_MODE	false	仅用于开发的标志，允许本地工具使用通配符 CORS。请勿在公开实例中启用。

若没有身份提供商，请勿将可写入的守护进程暴露到公共互联网。对于公开的只读演示， 请在反向代理处阻止 /mcp 和会修改数据的 HTTP 路由；参见 SECURITY.md 和 docs/22-public-demo.md。 守护进程自身还会设置基准安全标头，包括 nosniff、 点击劫持防护、引用来源策略，以及强化的资源 blob CSP。

对于可写入的公开实例或跨设备实例，请遵循 docs/oauth-setup.md。其中介绍了 GitHub OAuth App 设置、 ${PINDOC_PUBLIC_BASE_URL}/auth/github/callback 回调规则、运行时 MCP 客户端注册，以及使用 PINDOC_FORCE_OAUTH_LOCAL 进行本地 OAuth QA。

开发

# Run Go tests. Integration tests that need Postgres are skipped unless
# PINDOC_TEST_DATABASE_URL is set.
go test ./...

# Web checks.
cd web
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit
pnpm build

# Full image build.
docker build -t pindoc-server:local .

若要在本地测试 OAuth Bearer 路径，同时仍通过 127.0.0.1 连接，请设置 PINDOC_FORCE_OAUTH_LOCAL=true；守护进程启动时会发出警告， 并要求环回 /mcp 调用携带 Bearer 令牌。

在没有本地 C 工具链的 Windows 主机上，请通过 Docker 运行 Go 测试：

docker run --rm -v "${PWD}:/work" -w /work golang:1.25 go test ./...

请对临时 Postgres/pgvector 数据库运行数据库集成测试； 切勿将 PINDOC_TEST_DATABASE_URL 指向个人或生产用 Pindoc 数据库。测试和插件固件必须明确选择启用 Reader 隔离： 将 projects.CreateProjectInput.ReaderHidden 设为 true，或在使用 SQL 插入时设置 projects.reader_hidden = TRUE。基于 Slug 前缀的检测已弃用，不再在请求时运行。迁移 0070 仅对旧版 Pindoc 使用的固件前缀执行一次性回填。

文档

• 文档中心
• 公开演示计划
• 公开演示故事路径
• 值得记录的产物策略
• 公开发布检查清单
• 贡献指南
• 安全
• 设计源说明

反馈

长期问题、功能请求和设计讨论请前往 GitHub Discussions。错误报告 请前往 GitHub Issues。维护者通常会在一天内回复。

状态

Pindoc 正在积极进行内部试用。本地自托管路径、Reader UI、项目/领域模型、工件提案流程、任务队列、修订历史、摘要以及真实嵌入提供方路径均已实现。公开开源发布计划目前聚焦于提升首次运行的可靠性、提供只读内部试用演示、完善 CI 和安全文档，以及更清晰地定位协作功能。

许可证

Apache License 2.0。详见 LICENSE。