feat: 落地 Git 仓库页与提交说明生成

.env.example

@@ -23,3 +23,8 @@ LLM_API_KEY=
 
 # OpenAI 兼容 Base URL，例如 https://api.openai.com/v1（可空）
 LLM_BASE_URL=
+
+# 本地 Git 仓库根。未设则用进程 cwd（从 server/ 启动时 cwd 不是仓根）。
+# 撤回会改磁盘。本地试用先跑 scripts/git-sandbox.sh，再把这里指到 tmp/git-sandbox。
+# 要操作本仓时显式写成仓根。pnpm dev:api 在沙箱存在时默认用沙箱。
+GIT_REPO=

.gitignore

@@ -1,6 +1,7 @@
 .env
 .env.local
 *.db
+tmp/
 .DS_Store
 node_modules
 .pnpm-store

AGENTS.md

@@ -2,23 +2,24 @@
 
 修改 CodeDock 代码前，先阅读 [`docs/architecture.md`](docs/architecture.md)。该文档是当前目录归属和模块边界的依据。
 
-Agent Loop 已闭环：用户发文本、装上下文、调模型、产出文字或 Tool、事件落库并由 SSE 消费。默认注册 `ping` 与记忆工具 `memory_read` / `memory_write` / `memory_search`，不实现文件 / Shell / Git。
+Agent Loop 已闭环：用户发文本、装上下文、调模型、产出文字或 Tool、事件落库并由 SSE 消费。默认注册 `ping` 与记忆工具 `memory_read` / `memory_write` / `memory_search`，不实现文件 / Shell / Git **工具**。Git 用户操作走 HTTP + `pkg/git`，不经过 Agent Tool。前端 Git 在 `packages/core/git`、`packages/views/git` 与 `apps/web` 的 `/git`，不扩 `AgentClient`。
 
 ## 目录放置规则
 
 - 服务启动、配置读取、Router 和依赖装配放在 `server/cmd/server`。
-- 大部分 HTTP 逻辑放在 `server/internal/handler`：Session / Message / Usage / Approval 的 CRUD，SSE，Run 的 Start / Continue / Cancel，审批裁决，以及用户侧记忆查看/删除。
+- 大部分 HTTP 逻辑放在 `server/internal/handler`：Session / Message / Usage / Approval 的 CRUD，SSE，Run 的 Start / Continue / Cancel，审批裁决，用户侧记忆查看/删除，以及 Git（直接调 `pkg/git`）。
 - Agent 运行时编排和 sqlc 持久化放在 `server/internal/agent`。
 - Markdown 记忆（热层目录+专题）与 context message 索引（冷层按工作区 FTS）放在 `server/internal/agent/memory`；不放 `pkg/memory`。memory 不 import 父包 `internal/agent`，不定义 Tool。
 - 具体工具定义放在 `server/internal/agent/tools`。工具名、入参/出参、schema、权限和编排都在本包；Execute 若要调外部能力，只通过 `Ports` 里的接口。Runtime `New` 时由 `cmd/server` 注入 `Ports` 的具体实现，再 `Register`。每个工具只定义入参/出参结构体，执行用 `encoding/json`，schema 从类型推断。`tools` 可 import `memory`，不 import 父包 `internal/agent`。
 - Agent 通用无状态逻辑放在 `server/pkg/agent`：类型、token 统计、提示词、上下文、Tool 抽象（不含具体工具定义）、Agent 配置、模型调用。
+- Git CLI 操作放在 `server/pkg/git`：无状态，不写产品流程；Handler 直接调用。不进 `pkg/agent`。
 - 进程内事件总线放在 `server/internal/events`。
 - 数据库入口和 sqlc 生成代码放在 `server/pkg/db`。
 - 数据库结构演进放在 `server/migrations`。
-- 无头业务放在 `packages/core`（`@codedock/core`）：按业务域拆（现有 `chat/`，以后 `auth/`、`memory/`），文件直接在域目录下，不要 `src/`。不依赖 React、Next、DOM、`process.env`。`baseUrl` / `userId` 由调用方注入。
+- 无头业务放在 `packages/core`（`@codedock/core`）：按业务域拆（现有 `chat/`、`git/`），文件直接在域目录下，不要 `src/`。不依赖 React、Next、DOM、`process.env`。`baseUrl` / `userId` 由调用方注入。Git 用独立 `GitClient`。
 - 无业务 UI 放在 `packages/ui`（`@codedock/ui`）：`components/`、`lib/`、`styles/`，不要 `src/`，不按业务域拆。不依赖 core，不知道 Session / Run / TimelineItem。
-- 组合层放在 `packages/views`（`@codedock/views`）：按业务域拆，与 core 对齐（现有 `chat/`）。包根 `provider.tsx` 注入 client。不 import `next/*`；导航用回调。不要 `src/`，不预建空业务域。
-- Web 路由和平台装配放在 `apps/web`：读 `NEXT_PUBLIC_*`、创建 `AgentClient`、包 `AgentProvider`、`router.push`。不解析 SSE。
+- 组合层放在 `packages/views`（`@codedock/views`）：按业务域拆，与 core 对齐（现有 `chat/`、`git/`）。包根 `provider.tsx` 注入 Agent client；Git 用 `views/git` 的 `GitProvider`。不 import `next/*`；导航用回调。不要 `src/`，不预建空业务域。
+- Web 路由和平台装配放在 `apps/web`：读 `NEXT_PUBLIC_*`、创建 `AgentClient` / `GitClient`、包对应 Provider、`router.push`。`/git` 放在 `(chat)` 组外。开发态切页顶栏只放 web。不解析 SSE。
 - 依赖方向：`apps/web` → `packages/views` → `packages/core`；`packages/views` → `packages/ui`。`ui` 不依赖 `core`。未来 CLI 只依赖 `core`。
 - 不要创建 `server/pkg/ai`。大模型调用属于 `pkg/agent`。
 

README.md

@@ -14,22 +14,27 @@ cp apps/web/.env.example apps/web/.env.local
 pnpm install
 ```
 
-API（默认 `http://localhost:8080`）：
+一次起 API + Web。若已有 `tmp/git-sandbox`，API 默认指到沙箱，避免在本仓上试撤回：
 
 ```bash
-cd server
-go run ./cmd/server
+pnpm dev
 ```
 
-服务会从当前目录向上查找 `.env`，在 `server/` 下启动也能读到仓库根的 `.env`。
+也可以分开起。API（默认 `http://localhost:8080`）：
+
+```bash
+pnpm dev:api
+```
+
+从 `server/` 直接 `go run` 时，未设 `GIT_REPO` 会用进程 cwd（`server/` 不是仓根）。服务会从当前目录向上查找 `.env`。
 
 Web（默认 `http://localhost:3000`）：
 
 ```bash
 pnpm dev:web
 ```
 
-浏览器打开 [http://localhost:3000](http://localhost:3000)。完整环境变量见 [`.env.example`](.env.example)，不要提交 `.env` 或密钥。
+浏览器打开 [http://localhost:3000](http://localhost:3000)。开发态顶栏可在对话和仓库之间切换。完整环境变量见 [`.env.example`](.env.example) 和 [`apps/web/.env.example`](apps/web/.env.example)，不要提交 `.env` 或密钥。
 
 ## 测试
 

apps/web/app/(chat)/layout.tsx

@@ -4,9 +4,9 @@ import { ChatHost } from "../chat-host";
 
 export default function ChatLayout({ children }: { children: ReactNode }) {
   return (
-    <>
+    <div className="h-full">
       <ChatHost />
       {children}
-    </>
+    </div>
   );
 }

apps/web/app/git-host.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { GitClient } from "@codedock/core/git";
+import { GitPage, GitProvider } from "@codedock/views/git";
+import { useMemo } from "react";
+
+import { apiBase } from "@/lib/env";
+
+export function GitHost() {
+  const client = useMemo(() => new GitClient({ baseUrl: apiBase }), []);
+
+  return (
+    <GitProvider client={client}>
+      <div className="h-full">
+        <GitPage />
+      </div>
+    </GitProvider>
+  );
+}

apps/web/app/git/page.tsx

@@ -0,0 +1,9 @@
+import { GitHost } from "../git-host";
+
+export default function GitRoutePage() {
+  return (
+    <div className="h-full">
+      <GitHost />
+    </div>
+  );
+}

apps/web/app/layout.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
 
 import { Providers } from "./providers";
+import { TestNav } from "./test-nav";
 import "./globals.css";
 
 const geistSans = Geist({
@@ -25,8 +26,11 @@ export default function RootLayout({ children }: LayoutProps<"/">) {
       lang="zh-CN"
       className={`${geistSans.variable} ${geistMono.variable} h-full dark antialiased`}
     >
-      <body className="flex min-h-full flex-col bg-background font-sans text-foreground antialiased">
-        <Providers>{children}</Providers>
+      <body className="flex h-full flex-col bg-background font-sans text-foreground antialiased">
+        <Providers>
+          {process.env.NODE_ENV === "development" ? <TestNav /> : null}
+          <div className="flex min-h-0 flex-1 flex-col">{children}</div>
+        </Providers>
       </body>
     </html>
   );

apps/web/app/test-nav.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+const items = [
+  { href: "/", label: "对话", match: (path: string) => path === "/" || path.startsWith("/s/") },
+  { href: "/git", label: "仓库", match: (path: string) => path === "/git" || path.startsWith("/git/") },
+] as const;
+
+export function TestNav() {
+  const pathname = usePathname();
+
+  return (
+    <nav className="flex h-9 shrink-0 items-center gap-1 border-b border-border bg-background px-3 text-xs">
+      <span className="mr-2 font-mono text-[10px] tracking-wider text-muted-foreground/70">
+        测试
+      </span>
+      <span className="mr-2 h-3 w-px bg-border" aria-hidden />
+      {items.map((item) => {
+        const active = item.match(pathname);
+        return (
+          <Link
+            key={item.href}
+            href={item.href}
+            className={
+              active
+                ? "rounded-md bg-muted px-2 py-1 font-medium text-foreground"
+                : "rounded-md px-2 py-1 text-muted-foreground hover:bg-accent hover:text-foreground"
+            }
+          >
+            {item.label}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}

apps/web/next.config.ts

@@ -5,6 +5,9 @@ const nextConfig: NextConfig = {
     "@codedock/core",
     "@codedock/ui",
     "@codedock/views",
+    "@git-diff-view/react",
+    "@git-diff-view/core",
+    "@git-diff-view/utils",
     "streamdown",
     "@streamdown/cjk",
     "@streamdown/code",

docs/architecture.md

@@ -26,6 +26,7 @@ server/internal/handler
     |-- CRUD / SSE / Start / Continue / Cancel / 审批 --> pkg/db/sqlite
     |-- 领取 Run 后的 Loop --> internal/agent
     |-- 用户记忆查看 / 删除 --> pkg/db/sqlite
+    |-- Git HTTP --> pkg/git（本机 CLI，无产品流程）
     |
     v
 server/internal/agent
@@ -37,6 +38,7 @@ server/internal/agent
     |
     v
 server/pkg/agent
+server/pkg/git
 ```
 
 `pkg/ai` 已删除。大模型调用放在 `pkg/agent`，由 `ModelConfig` 在方法内创建，不由 Runtime 注入。
@@ -55,7 +57,7 @@ CodeDock/
 ├── server/
 │   ├── cmd/server/              # 服务启动、配置、Router 和依赖装配
 │   ├── internal/
-│   │   ├── handler/             # 大部分 HTTP：CRUD、SSE、Start / Continue / Cancel、记忆查看/删除
+│   │   ├── handler/             # 大部分 HTTP：CRUD、SSE、Start / Continue / Cancel、记忆查看/删除、Git
 │   │   ├── agent/               # 运行时编排 + sqlc 持久化
 │   │   │   ├── memory/          # 热层目录+专题，冷层工作区 FTS 索引
 │   │   │   └── tools/           # 具体工具定义：ping、memory_*
@@ -66,6 +68,7 @@ CodeDock/
 │   │   └── util/
 │   ├── pkg/
 │   │   ├── agent/               # 全部通用无状态逻辑，含模型调用与 Tool 抽象
+│   │   ├── git/                 # 无状态 Git CLI 操作，供 Handler 直接调用
 │   │   └── db/                  # Client 与 sqlc 生成代码
 │   ├── migrations/
 │   ├── go.mod
@@ -85,6 +88,7 @@ cmd/server
 internal/handler
   -> pkg/db/sqlite.Queries
   -> pkg/agent          # 映射响应、token 统计、Profile 装配
+  -> pkg/git            # 本机 Git CLI 操作
   -> internal/agent     # Worker 领取后的 Loop
   -> internal/agent/memory  # 用户侧记忆响应类型
 
@@ -112,9 +116,13 @@ pkg/agent
   不持有包级状态，不查库
   Tool 包只含接口、Registry、Dispatch，不含具体工具定义
 
+pkg/git
+  不依赖 handler、internal、sqlc
+  无状态，只 exec 本机 git；不写产品流程
+
 packages/core
   不依赖 React、Next、DOM、process.env、AI SDK
-  按业务域拆目录（chat、以后的 auth / memory），不要 src/
+  按业务域拆目录（chat），不要 src/
   文件直接落在 packages/core/<domain>/
   baseUrl / userId 由调用方注入
 
@@ -149,8 +157,9 @@ apps/web
 - 事件 JSON 回放：`GET /sessions/{id}/event-log`，供前端一次 hydrate，不替代 SSE 直播
 - Run 的 Start / Continue / Retry / Cancel 和审批裁决直接在 Handler 中处理，需要执行时再交给 Worker
 - 同一 Session 只有一个 active Run：`interrupt` 先取消再开新 Run；`queue` 只落库，当前结束后自动领取
+- Git HTTP（`/git/*`）：校验 checkout、组响应，直接调用 `pkg/git`。`GIT_REPO` 为空则用进程 cwd。`GET /git/status` 回 `SiteState` 整局（含 `is_repo`、跟踪、ahead/behind、integrating）
 
-Handler 直接依赖 `*sqlite.Queries`，不经过 Store 接口。
+Handler 直接依赖 `*sqlite.Queries`，不经过 Store 接口。Git 不查库。
 
 ### `internal/agent`
 
@@ -185,6 +194,10 @@ Handler 直接依赖 `*sqlite.Queries`，不经过 Store 接口。
 
 每个工具只定义入参/出参结构体；执行用 `encoding/json`，给模型的 schema 由 `jsonschema.For` 从类型推断。Agent 通过 `Profile.Tools.Names` 绑定工具。运行模式提供 `read` / `write` / `memory` 能力，只有模式覆盖了工具声明的全部能力时该工具才对模型可见且可 Dispatch。记忆工具声明 `memory`。审批仍由工具声明 `RequiresApproval`，`ask_for_approval` 暂停、`auto_approve` / `yolo` 自动过。一批待批工具对应一条审批，一次提交审完再流转。不 import 父包 `internal/agent`。测试用 Tool 可留在测试文件。
 
+### `pkg/git`
+
+无状态 Git CLI：`Open` / `Status`（`SiteState` 整局）/ Diff / 图 / 暂存提交 / reset / revert / 推拉 / remote / 分支 / worktree / `stash create` 副本 / 冲突读写。不进 `pkg/agent`，不写 HTTP 或产品流程。Workspace / Branch / Undo / 说明 / Agent 快照的产品组合在 Handler。
+
 ### `pkg/agent`
 
 全部 Agent 通用逻辑，方法无状态：
@@ -208,7 +221,7 @@ Handler 直接依赖 `*sqlite.Queries`，不经过 Store 接口。
 
 ### `packages/core`
 
-跨端无头业务，无 UI。按业务域拆目录，文件直接放在 `packages/core/<domain>/`，不要 `src/`。现有 `chat/`：Session / Message / Run / 审批的 HTTP、SSE、Timeline reducer。有鉴权再加 `auth/`，有记忆再加 `memory/`，不预建空目录。`baseUrl` / `userId` 由调用方注入。不依赖 React。第一版 thinking 用 Run 状态（`queued` / `loading_context` / `running_llm`），不是模型 reasoning token。
+跨端无头业务，无 UI。按业务域拆目录，文件直接放在 `packages/core/<domain>/`，不要 `src/`。现有 `chat/`：Session / Message / Run / 审批的 HTTP、SSE、Timeline reducer。有鉴权再加 `auth/`，有记忆再加 `memory/`，Git 前端在 `git/`（`GitClient`，不扩 `AgentClient`）。`baseUrl` / `userId` 由调用方注入。不依赖 React。第一版 thinking 用 Run 状态（`queued` / `loading_context` / `running_llm`），不是模型 reasoning token。
 
 ### `packages/ui`
 
@@ -222,11 +235,11 @@ Handler 直接依赖 `*sqlite.Queries`，不经过 Store 接口。
 
 ### `packages/views`
 
-组合 core + ui。按业务域拆，与 core 对齐，不要 `src/`。现有 `chat/`：`ChatPage`、侧栏、瀑布、审批、prompt。包根 `provider.tsx` 注入 `AgentClient` + `userId`。`ChatPage` 接 `sessionId` 与 `onOpenSession`。不 import `next/*`。新业务新建目录，不预建 Issue / Task / Review / Workspace。
+组合 core + ui。按业务域拆，与 core 对齐，不要 `src/`。现有 `chat/`：`ChatPage`、侧栏、瀑布、审批、prompt。包根 `provider.tsx` 注入 `AgentClient` + `userId`。`ChatPage` 接 `sessionId` 与 `onOpenSession`。Git 在 `git/`：`GitProvider` 只注入 `GitClient`，不进 `AgentContext`。不 import `next/*`。新业务新建目录，不预建 Issue / Task / Review / Workspace。
 
 ### `apps/web`
 
-路由、`NEXT_PUBLIC_API_BASE` / `NEXT_PUBLIC_USER_ID`、创建 `AgentClient`、包 `AgentProvider`、`router.push`。本机 Web 直连 `:8080`（CORS）。
+路由、`NEXT_PUBLIC_API_BASE` / `NEXT_PUBLIC_USER_ID`、创建 `AgentClient`、包 `AgentProvider`、`router.push`。本机 Web 直连 `:8080`（仅回环 Origin 的 CORS）。Git 页在 `(chat)` 组外的 `/git`，只装配 `GitClient`。开发态顶栏（对话 / 仓库）只放 web，views 不知道路径。
 
 ## 组装关系
 
@@ -248,8 +261,8 @@ Worker
 
 ## 配置
 
-`LLM_PROVIDER`（`openai` | `fake`，默认 `fake`）、`LLM_MODEL`、`LLM_API_KEY`、`LLM_BASE_URL`。Handler 创建 Run 时写入 `RunConfigSnapshot`，后续 Turn 只读快照。
+`LLM_PROVIDER`（`openai` | `fake`，默认 `fake`）、`LLM_MODEL`、`LLM_API_KEY`、`LLM_BASE_URL`。`GIT_REPO` 指向本地仓库根，未设则用进程 cwd（不向上找 `.git`）。Handler 创建 Run 时写入 `RunConfigSnapshot`，后续 Turn 只读快照。
 
-HTTP 出站领域对象使用 snake_case JSON。Router 对带 Origin 的请求回显 CORS，便于本机 Web 直连 `:8080`。Web 用 `NEXT_PUBLIC_API_BASE`（默认 `http://localhost:8080`）和 `NEXT_PUBLIC_USER_ID`（默认 `local`）。
+HTTP 出站领域对象使用 snake_case JSON。Router 只对本地回环 Origin 放行 CORS，便于本机 Web 直连 `:8080`。Web 用 `NEXT_PUBLIC_API_BASE`（默认 `http://localhost:8080`）和 `NEXT_PUBLIC_USER_ID`（默认 `local`）。
 
 修改 Agent 能力或跨端协议时，需要检查契约、取消与终态、流式事件语义以及敏感信息处理。

package.json

@@ -2,6 +2,8 @@
   "name": "codedock",
   "private": true,
   "scripts": {
+    "dev": "sh scripts/dev.sh",
+    "dev:api": "sh scripts/dev-api.sh",
     "dev:web": "pnpm --filter web dev",
     "build:web": "pnpm --filter web build",
     "test:client": "pnpm --filter @codedock/core test",