project-atlas 0.1.0

package/docs/site/publish-now.md

@@ -0,0 +1,166 @@
+# 现在发布指南
+
+本文记录当前仓库如果要马上发布到 npm，应按什么顺序做。
+
+## 当前结论
+
+- 包名是 `project-atlas`。
+- 当前版本是 `0.1.0`。
+- npm registry 当前没有同名包，可以按首次发布处理。
+- 当前发布方式是手工发布，不做 GitHub Release，不做自动发布。
+- 发布前必须保证本地 `main` 已经推送到 `origin/main`。
+- `package.json` 当前 repository URL 指向 `project-atlas`。如果 GitHub 仓库还没有改名，先完成仓库改名，或者把 repository URL 调整为当前真实仓库。
+
+## 发布前整理
+
+先确认工作区和分支状态：
+
+```bash
+git status --branch --short
+```
+
+如果看到 `main...origin/main [ahead 1]`，说明本地有提交还没有推送。先推送：
+
+```bash
+git push origin main
+```
+
+确认 `CHANGELOG.md`。如果你要发布 `0.1.0`，就把本次要发布的 `Unreleased` 内容归入 `0.1.0`，或者确认 `Unreleased` 只保留下一版内容。
+
+确认 GitHub 远端名称。如果要让 npm 页面指向 Project Atlas 仓库，先在 GitHub 上把仓库改名为 `project-atlas`，再更新本地 remote：
+
+```bash
+git remote set-url origin https://github.com/clclo121/project-atlas.git
+git remote -v
+```
+
+## 本地验证
+
+固定执行：
+
+```bash
+npm run lint:types
+npm test
+npm run verify
+npm pack --dry-run
+node dist/index.js --help
+node dist/index.js init --help
+node dist/index.js context --help
+node dist/index.js propose --help
+node dist/index.js remember --help
+node dist/index.js check --help
+node dist/mcp.js --help
+```
+
+`npm pack --dry-run` 应包含：
+
+- `README.md`
+- `LICENSE`
+- `CHANGELOG.md`
+- `dist/`
+- `adapters/`
+- `schema/`
+- `templates/`
+- `docs/site/`
+- `package.json`
+
+不应包含：
+
+- `test/`
+- `src/`
+- `docs/development-log/`
+- `node_modules/`
+
+## npm 登录
+
+确认 npm registry：
+
+```bash
+npm config get registry
+```
+
+期望是：
+
+```text
+https://registry.npmjs.org/
+```
+
+登录并确认账号：
+
+```bash
+npm login
+npm whoami
+```
+
+如果开启了两步验证，按 npm CLI 提示输入验证码。
+
+## 首次发布
+
+发布前再次确认版本：
+
+```bash
+node -p "require('./package.json').name + '@' + require('./package.json').version"
+```
+
+当前应输出：
+
+```text
+project-atlas@0.1.0
+```
+
+执行发布：
+
+```bash
+npm publish
+```
+
+当前是非 scoped 包，不需要 `--access public`。如果以后改成 `@scope/project-atlas` 这类 scoped 包，再使用：
+
+```bash
+npm publish --access public
+```
+
+## 发布后验证
+
+确认 npm 上的版本：
+
+```bash
+npm view project-atlas version
+```
+
+用临时目录安装验证：
+
+```bash
+tmpdir=$(mktemp -d)
+cd "$tmpdir"
+npm init -y
+npm install project-atlas
+npx project-atlas --help
+npx project-atlas-mcp --help
+```
+
+## 打 tag 和推送
+
+npm 发布成功后再打 tag：
+
+```bash
+git tag v0.1.0
+git push origin main --tags
+```
+
+如果 tag 已存在，不要覆盖。先检查：
+
+```bash
+git tag --list "v0.1.0"
+```
+
+## 失败处理
+
+如果 `npm publish` 失败：
+
+- `403 Forbidden` 通常是没有权限、包名不可用、账号未登录或版本已存在。
+- `402 Payment Required` 通常和私有包或组织权限有关，当前项目应发布为 public。
+- `ENEEDAUTH` 表示没有登录，重新执行 `npm login`。
+- `You cannot publish over the previously published versions` 表示版本号已发布，需要升级 `package.json` 版本。
+
+不要在发布失败后直接改 tag。只有 npm 发布成功后才创建版本 tag。

package/docs/site/quick-start.md

@@ -0,0 +1,128 @@
+# 快速开始
+
+本文帮助新用户在 10 分钟内跑通 Project Atlas 的最小流程。
+
+## 1. 准备项目
+
+进入一个 Git 仓库，安装并构建：
+
+```bash
+npm install
+npm run build
+```
+
+初始化知识库：
+
+```bash
+node dist/index.js init --repo /path/to/repo --template generic-service
+```
+
+Java 后端项目可以使用：
+
+```bash
+node dist/index.js init --repo /path/to/repo --template java-backend
+```
+
+前端项目可以使用：
+
+```bash
+node dist/index.js init --repo /path/to/repo --template frontend-app
+```
+
+## 2. 读取上下文
+
+按关键词读取紧凑上下文：
+
+```bash
+node dist/index.js context --repo /path/to/repo --query "order payment" --budget 8000
+```
+
+按来源文件反查知识文档：
+
+```bash
+node dist/index.js context --repo /path/to/repo --source-file README.md --format json
+```
+
+按项目记忆元数据读取上下文：
+
+```bash
+node dist/index.js context --repo /path/to/repo --memory-type decision --topic payment --scope backend --format json
+```
+
+## 3. 生成 proposal
+
+准备 `updates.json`：
+
+```json
+{
+  "source_files": ["README.md"],
+  "updates": [
+    {
+      "target": "knowledge/project/overview.md",
+      "content": "# Project Overview\n\nRecord the verified project overview here.\n"
+    }
+  ]
+}
+```
+
+生成证据：
+
+```bash
+node dist/index.js propose --repo /path/to/repo --updates-file updates.json --reason "refresh overview"
+```
+
+## 4. 沉淀项目记忆
+
+如果任务结束后产生了稳定事实、决策或经验，可以准备 `memory.json`：
+
+```json
+{
+  "schema_version": "1.0",
+  "source_files": ["README.md"],
+  "memories": [
+    {
+      "target": "knowledge/decisions/payment-review.md",
+      "memory_type": "decision",
+      "topic": "payment review",
+      "scope": "backend",
+      "confidence": 0.9,
+      "summary": "Payment review must check duplicate callbacks.",
+      "body": "When changing payment callbacks, review duplicate notification handling before changing signature validation."
+    }
+  ]
+}
+```
+
+生成记忆 proposal：
+
+```bash
+node dist/index.js remember --repo /path/to/repo --candidate-file memory.json --reason "capture payment review memory"
+```
+
+`remember` 只生成 proposal，不直接写 `knowledge/`。
+
+## 5. Review 后再写入
+
+查看 review summary：
+
+```bash
+node dist/index.js review-summary --repo /path/to/repo
+```
+
+确认无敏感阻断、无不该写入的内容后，由人执行：
+
+```bash
+node dist/index.js apply --repo /path/to/repo --proposal-id <id> --confirm
+```
+
+Project Atlas 不允许 agent 直接 apply。这个边界是工具可控的关键。
+
+## 6. 健康检查
+
+发布前或交接前运行：
+
+```bash
+node dist/index.js check --repo /path/to/repo --format json
+```
+
+`check` 会检查 manifest、必需文件、frontmatter、source hash、缺失来源、空文档、坏相对链接、重复 topic 和 schema JSON。

package/docs/site/release-process.md

@@ -0,0 +1,94 @@
+# 发布流程
+
+本文约定 Project Atlas 的轻量发布治理方式。当前不做自动发布，也不创建 GitHub Release。
+
+如果你现在就准备发布，先看 [现在发布指南](publish-now.md)。本文偏长期规则，`publish-now.md` 偏本次操作步骤。
+
+## 版本规则
+
+使用 SemVer：
+
+- `MAJOR` 用于不兼容的 CLI、schema 或 evidence 格式变化。
+- `MINOR` 用于新增命令、参数、schema 字段或 adapter 能力。
+- `PATCH` 用于 bug fix、文档修正和不改变行为的维护。
+
+当前公开 schema 版本为 `1.0`。不兼容 schema 变化必须更新 schema 版本，并在 changelog 中说明迁移方式。
+
+## Changelog
+
+每次发布前更新 `CHANGELOG.md`：
+
+- 新增能力写清楚用户能怎么用。
+- 行为变更写清楚影响范围。
+- 安全边界变化必须单独说明。
+- 依赖和 Node 版本要求变化必须说明。
+
+## 发布前检查
+
+发布前固定执行：
+
+```bash
+npm run lint:types
+npm test
+npm pack --dry-run
+npm run verify
+node dist/index.js --help
+node dist/index.js init --help
+node dist/index.js context --help
+node dist/index.js propose --help
+node dist/index.js remember --help
+node dist/index.js check --help
+node dist/mcp.js --help
+```
+
+`npm pack --dry-run` 应包含：
+
+- `README.md`
+- `LICENSE`
+- `CHANGELOG.md`
+- `dist/`
+- `adapters/`
+- `schema/`
+- `templates/`
+- `docs/site/`
+- `package.json`
+
+不应包含：
+
+- `test/`
+- `src/`
+- `docs/development-log/`
+- `node_modules/`
+
+## 发布步骤
+
+当前项目只沉淀手工流程：
+
+1. 更新版本号和 `CHANGELOG.md`。
+2. 执行发布前检查。
+3. 检查 `npm pack --dry-run` 内容。
+4. 确认当前分支干净。
+5. 创建提交。
+6. 推送到 `origin/main`。
+7. 执行 `npm login` 和 `npm whoami`。
+8. 执行 `npm publish`。
+9. 创建版本 tag 并推送。
+
+首次发布当前包名时可以直接使用：
+
+```bash
+npm publish
+git tag v0.1.0
+git push origin main --tags
+```
+
+如果 npm 要求二次验证，按 npm CLI 提示完成一次性验证码输入。
+
+## 当前仓库发布注意事项
+
+- 当前 package name 是 `project-atlas`。
+- 当前 package version 是 `0.1.0`。
+- 当前 npm registry 未发现同名包，可以按首次发布处理。
+- 发布前要确认 `CHANGELOG.md` 中 `Unreleased` 的内容已经归入要发布的版本。
+- 如果本地 `main` 领先 `origin/main`，先推送代码，再发布 npm 包。
+- 如果 GitHub 仓库还没有改名为 `project-atlas`，先改远端仓库名，或者在发布前把 `package.json` 的 repository URL 改回真实仓库地址。

package/docs/site/security-faq.md

@@ -0,0 +1,55 @@
+# 安全 FAQ
+
+## Agent 能直接写知识库吗
+
+不能。Project Atlas 的 agent adapter 和 MCP server 都不提供 apply 工具。
+
+Agent 可以：
+
+- scan
+- context
+- stale
+- propose
+- remember
+- check
+- review-summary
+
+Agent 不能：
+
+- 调用 apply tool
+- 绕过 proposal 直接写 `knowledge/**`
+- 在非 TTY 环境执行 apply
+
+## 为什么 apply 必须在终端执行
+
+`apply` 会真实写入知识文档。Project Atlas 要求人在终端 TTY 中确认，避免模型在没有人工检查时直接改知识库。
+
+## 敏感内容怎么处理
+
+扫描配置时只输出规则类型和文件路径，不输出真实值。
+
+proposal 命中敏感规则时，状态会变成 `blocked_sensitive`，并且不会保存敏感原文。
+
+## 外部证据安全吗
+
+`external_evidence` 只保存外部工具给出的结构化摘要。它不会运行 Serena、Codebase-Memory、Aider Repo Map 等工具，也不会把这些工具作为依赖。
+
+导入外部证据前，团队仍然要确认 JSON 文件里没有密钥、token、密码或客户敏感信息。
+
+## MCP 有写入风险吗
+
+`project-atlas-mcp` 是本地 stdio MCP server，只暴露安全工具。它不暴露 apply。
+
+如果某个 MCP 客户端支持自定义命令，团队不要把 `project-atlas apply` 配成模型可调用工具。
+
+## 项目记忆会不会变成个人记忆
+
+不会。`remember` 只读取用户提供的结构化候选 JSON，只生成 proposal。它不读取聊天记录，不写个人长期记忆库，也不自动总结本地会话。
+
+项目记忆进入 `knowledge/` 后就是团队共享内容，必须接受 Git review。需要替换已有记忆时，命令要显式传 `--replace-existing`。
+
+## `.project-atlas/` 要提交吗
+
+默认不要提交。`.project-atlas/proposals/` 是本地证据目录，通常用于当前 review 和人工确认。
+
+稳定知识应该落在 `knowledge/**`，并通过 Git 审查。

package/docs/site/team-rollout.md

@@ -0,0 +1,59 @@
+# 团队落地流程
+
+Project Atlas 的团队落地建议从一个项目开始，不要一开始就要求所有项目统一迁移。
+
+## 第一步 选择试点项目
+
+优先选择这些项目：
+
+- 团队经常问重复问题。
+- 业务流程相对稳定。
+- README 或开发日志已经有基础资料。
+- 最近会有真实需求进入开发。
+
+## 第二步 初始化知识库
+
+由项目负责人执行：
+
+```bash
+project-atlas init --repo /path/to/repo --template generic-service
+```
+
+Java 后端、前端项目可以选择对应模板。
+
+## 第三步 建立协作规则
+
+建议团队约定：
+
+- 需求开始前，agent 先读 `project-atlas context`。
+- 需求结束后，只更新确实稳定的知识。
+- 所有知识更新先走 `project-atlas propose`。
+- 项目记忆先走 `project-atlas remember`，再由人 review。
+- reviewer 先读 `project-atlas review-summary`。
+- 只有人能执行终端 apply。
+
+## 第四步 接入 agent
+
+本地 agent 可以选一种方式：
+
+- 直接调用 `project-atlas` CLI。
+- 使用 OpenCode adapter。
+- 使用 `project-atlas-mcp` 接入 Claude Code、Cursor 或 Continue。
+
+所有 adapter 都保持同一条安全边界。agent 可以生成 proposal，不能直接写入知识库。
+
+MCP 里的 `project_atlas_remember` 和 `project_atlas_check` 也是安全工具。前者只生成记忆 proposal，后者只做健康检查。
+
+## 第五步 固定检查点
+
+建议在这些节点检查知识库：
+
+- 新需求完成。
+- 发布前。
+- 新同事接手项目。
+- 关键接口或流程调整后。
+- 决策、经验或项目事实被写入记忆前。
+
+建议把 `project-atlas check --repo /path/to/repo --format json` 放进团队本地检查清单。它能在 review 前暴露缺来源、过期来源、坏链接和重复 topic。
+
+团队落地的目标不是文档越多越好，而是让可复用知识保持可信。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "project-atlas",
+  "version": "0.1.0",
+  "description": "Project Atlas is a Git-first project knowledge base CLI for AI coding agents and reviewers.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "project-atlas": "./dist/index.js",
+    "project-atlas-mcp": "./dist/mcp.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clclo121/project-atlas.git"
+  },
+  "keywords": [
+    "ai-coding",
+    "project-atlas",
+    "knowledge-base",
+    "project-memory",
+    "opencode",
+    "cli",
+    "git"
+  ],
+  "files": [
+    "dist",
+    "adapters",
+    "schema",
+    "templates",
+    "docs/site",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint:types": "tsc --noEmit -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "verify": "npm run lint:types && npm test",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "zod": "^4.4.3"
+  }
+}

package/schema/context-pack.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/liuliuyun/project-atlas/schema/context-pack.schema.json",
+  "title": "project-atlas context pack",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "budget", "budget_used", "truncated", "text", "items"],
+  "properties": {
+    "schema_version": {
+      "const": "1.0"
+    },
+    "budget": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "budget_used": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "truncated": {
+      "type": "boolean"
+    },
+    "text": {
+      "type": "string"
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source", "source_type", "priority", "content"],
+        "properties": {
+          "source": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_type": {
+            "enum": ["openspec_change", "openspec_spec", "knowledge"]
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "content": {
+            "type": "string"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "memory_type": {
+                "enum": ["decision", "experience", "project_fact"]
+              },
+              "topic": {
+                "type": "string"
+              },
+              "scope": {
+                "type": "string"
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "owner": {
+                "type": "string"
+              },
+              "related_docs": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}