Pindoc

面向 AI 辅助开发的团队代码绑定记忆系统。 代理负责编写持久化记录；人类负责审查、讨论和引导。

Pindoc 是一个为使用 AI 编程代理的团队提供的自托管项目记忆系统。它将代理有用的发现转化为类型化的制品：决策、调试路径、任务收尾、验证说明以及与代码关联的分析。每个制品都限定在项目区域内，并绑定到提交、文件、URL、资源或相关的 Pindoc 制品上。

它仍然是你从不主动输入的维基，但其目的并非为了自动化而自动化。Pindoc 保留了团队成员和未来代理可以重用的代理工作成果。

为什么存在

AI 编程会话虽然高效，但团队上下文仍然会遗漏：

• 调试路径随着终端会话的结束而消失，

• 同样的决策被反复向每个新代理解释，

• 有用的分析留在了某个操作员的聊天记录中，而不是成为团队知识，

• 重复的文档在维基、问题追踪器、PR 和提交信息中堆积，

• 在真实的项目环境中，发现问题的人并不总是能立即更改代码；结构化的证据有助于团队进行讨论和决策。

Pindoc 将值得保留的代理工作转化为可搜索、代码绑定的团队记忆。下一位团队成员或编程代理可以在编辑前询问 Pindoc 什么是重要的。

Pindoc 的独特之处

• 协作记忆层：制品是为团队成员和未来代理编写的，而不是作为私人的聊天摘要。

• 仅限代理的写入界面：阅读器 UI 用于阅读和审查；持久化写入通过代理进行。

• MCP 原生工作流：诸如 pindoc.context_for_task、pindoc.artifact.propose 和 pindoc.task.queue 等工具用于规范代理行为，而不是充当简单的 CRUD API。

• 类型化制品：决策、分析、调试、流程、任务、TC（测试用例）、术语表和领域包类型。

• 代码绑定记忆：制品可以指向提交、文件、行范围、资源、URL 和相关制品。

• 设计上值得记录：Pindoc 避免了原始聊天存档，仅保留具有未来价值的决策、分析、调试路径、验证和任务上下文。

• 多项目守护进程：一个 /mcp 端点可以服务多个项目；每个工具调用都携带 project_slug。

• 优先自托管：Docker Compose 可启动 Postgres、pgvector、Pindoc 守护进程和阅读器 SPA。

公开演示

只读的公开演示是后续计划的一部分，不属于本次开源发布的内容。在它发布之前，README、docs/ 和自托管克隆是主要的证明。想要端到端评估 Pindoc 的操作员可以运行 docker compose up -d --build 并检查他们自己的制品。

后续演示计划保留在 Public Demo Plan 中，以便在托管实例合适时使用。

快速入门

先决条件：

• Docker 27+

• 建议本地试用或小团队使用 2 个 CPU 核心和 4 GB 内存

• 建议为 Docker 镜像、Postgres 数据和嵌入缓存预留 5 GB 可用磁盘空间；2 GB 是全新克隆的最低要求

• 首次运行时需要出站 HTTPS，以便缓存捆绑的 EmbeddingGemma 模型和运行时

• 仅主机原生开发需要 Go 1.25+

• 仅 Docker 之外的 Web 开发需要 Node 20.15+ 和 pnpm 10+

默认的 Docker 路径包括通过捆绑的 EmbeddingGemma Q4 ONNX 提供程序进行的语义搜索，因此不需要嵌入辅助容器。请参阅 System Requirements 获取最低和可选的部署配置。

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

打开阅读器：

http://localhost:5830/

在全新的实例上，/ 会重定向到第一个项目向导。直接打开该向导：

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

连接 MCP 客户端

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

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

项目范围未编码在 URL 中。代理在项目范围的工具调用上传递 project_slug。由 pindoc.harness.install 生成的工作区将该 slug 存储在 PINDOC.md 的 frontmatter 中。

常见工作流

要求代理在项目上下文中开始工作：

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. 更新任务验收和收尾状态

配置

默认的 Docker 路径是单用户且仅限回环地址：

在没有身份提供程序的情况下，不要将可写的守护进程暴露给公共互联网。对于公共只读演示，请在反向代理处阻止 /mcp 和变异的 HTTP 路由；请参阅 SECURITY.md 和 docs/22-public-demo.md。

对于可写的公共或跨设备实例，请遵循 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 持有者路径同时仍通过 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 ./...

文档

• 文档中心

• 公开演示计划

• 公开演示故事路径

• 值得记录的制品策略

• 公开版本发布清单

• 贡献

• 安全

• 设计来源说明

状态

Pindoc 处于活跃的内部试用阶段。本地自托管路径、阅读器 UI、项目/区域模型、制品提案流程、任务队列、修订历史、摘要和真实的嵌入提供程序路径均已实现。公开开源发布轨道专注于首次运行的可靠性、只读试用演示、CI、安全文档和更清晰的协作定位。

许可证

Apache License 2.0。请参阅 LICENSE。