Ulw/mvp integration 20260710

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+
+on: [push, pull_request]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24.16.0
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm run test:unit
+      - run: npm run test:smoke
+      - run: npm run test:e2e
+      - run: npm audit --package-lock-only --audit-level=moderate

.gitignore

@@ -2,7 +2,10 @@ node_modules/
 dist/
 out/
 generated/
+handoff/
 .env
 *.log
+.debug-journal.md
 .omo/
 .claude/
+.worktrees/

AGENT.md

@@ -0,0 +1,129 @@
+# Code2Lark (Lark-deployer)
+
+Code2Lark is a build-time generator. It analyzes an existing service and produces reviewable Feishu/Lark adapter packages. It builds and verifies integration artifacts; it does not own the target service lifecycle.
+
+## Architecture
+
+```text
+analyze -> plan -> context -> generate -> verify -> doctor -> handoff
+                                      \-> install (Mode B only)
+```
+
+The CLI currently exposes 13 commands through `src/index.ts`:
+
+- `analyze`, `plan`, `generate`, `context`
+- `configure`, `status`, `readiness`, `doctor`
+- `evidence`, `handoff`, `init-local`, `install`, `verify`
+
+The project uses TypeScript strict mode, ES2022/NodeNext, and Node.js 24.16 or newer.
+
+## Delivery Modes
+
+- `embedded-adapter`: generated adapter for an existing Feishu SDK host.
+- `self-hosted-runtime`: generated Python `feishu-host/` using the Feishu SDK long connection.
+- `standalone-runtime`: optional reference Node.js host.
+
+Host receive modes are `embedded-long-connection`, `embedded-webhook`, `hybrid`, and `standalone-runtime`. Long connection uses `card.action.trigger`.
+
+- Mode A keeps the Feishu host outside the target project.
+- Mode B installs an isolated host module under the target project, currently `integrations/lark/`.
+
+## Structural Analysis Backends
+
+`analyze` accepts `--backend auto|internal|codegraph`.
+
+- `internal`: use the built-in source scan.
+- `auto`: try codegraph, then safely fall back to internal when codegraph is unavailable, uninitialized, stale, incomplete, or invalid.
+- `codegraph`: require a user-maintained fresh index and fail clearly instead of silently falling back.
+
+Only these read-only codegraph commands are allowed:
+
+```text
+codegraph status <repo> --json
+codegraph query route --kind route --path <repo> --json
+```
+
+Code2Lark must never install codegraph or run codegraph `init`, `sync`, reindex, or index-rebuild operations. External results are normalized at the boundary; profile and downstream code must not depend on the external schema.
+
+## Interaction Profiles
+
+Target-specific mapping lives in `src/profiles/`:
+
+| Profile | Source | Role |
+| --- | --- | --- |
+| `image-agent-web` | `src/profiles/image-agent-web.ts` | Stable sample baseline |
+| `calendar-stock-updater` | `src/profiles/calendar-stock-updater.ts` | Typed calendar task cards and handlers |
+| `generic-http-api` | analyzer/generator fallback | Coarse generic HTTP mapping |
+
+Profiles own detection, capability mapping, Card JSON 2.0 builders, handlers, validation, and profile-specific strict checks. `handleCardAction` is the calendar adapter facade.
+
+Generated adapter TypeScript must pass `tsc --noEmit --strict`. Do not emit or add `@ts-nocheck`, `@ts-ignore`, `@ts-expect-error`, or `any` to bypass type errors.
+
+## Calendar Mode B Contract
+
+The current calendar correction contract is strict:
+
+- Schema remains `0.2`.
+- The only target calls are `GET /api/state`, `POST /api/run`, and `POST /api/stop`.
+- Run/stop prepare, confirm, and cancel are host-local card actions, not target HTTP endpoints.
+- The browser-only `/api/events` stream is supporting context, not a card action endpoint.
+- `generate` never writes the target project.
+- `install` defaults to dry-run and must write nothing.
+- `install --apply` may write only `integrations/lark/**`.
+- Do not modify target root `package.json`, startup scripts, Docker files, business code, or Web UI.
+- Treat the original target as read-only. Use a disposable replay/copy for installation verification.
+- The install gate probes `GET /api/state`, validates source hashes and managed-file conflicts, and rejects symlink/junction paths before writes.
+- The installed module owns its `.env`, dependencies, tests, startup, confirmation state, idempotency, authorization, and audit output.
+
+The generated package remains the source of truth. Do not replace generated directories manually; use the `install` command.
+
+```powershell
+node dist/index.js generate <analysis-workspace> --out <generated-package> --mode embedded-adapter --host-mode embedded-long-connection
+node dist/index.js verify <generated-package> --mode embedded-adapter --host-mode embedded-long-connection --strict
+node dist/index.js install <generated-package> --target <calendar-replay> --target-base-url http://127.0.0.1:3069
+node dist/index.js install <generated-package> --target <calendar-replay> --target-base-url http://127.0.0.1:3069 --apply
+```
+
+After apply, run `npm install`, `npm test`, and `npm start` inside `<calendar-replay>/integrations/lark`. Run the calendar target service separately.
+
+## Generated Package
+
+```text
+generated/<target>-lark/
+  manifest/
+  adapter/
+  docs/
+  integrations/lark/       # calendar Mode B installable closure
+  sidecar-long-connection/ # host contract/local check when applicable
+  bot-runtime/              # optional standalone mode only
+  feishu-host/              # optional self-hosted mode only
+```
+
+Card payloads use JSON 2.0 (`schema: "2.0"`, `body.elements`, callback behaviors). Manifest schema `0.2` is mandatory. Infrastructure credentials belong in local `.env` files; business parameters belong in cards.
+
+## Governing Documents
+
+- `docs/codegraph-structural-backend-correction-task-book.md`: structural backend and final replay contract.
+- `docs/calendar-stock-updater-mode-b-correction-task-book.md`: current calendar Mode B correction contract.
+- `docs/capability-validation-matrix.md`: validation fact matrix.
+- `docs/project-status.md`: current project status and evidence summary.
+- `docs/calendar-stock-updater-mode-b-long-connection-task-book.md`: superseded historical plan; do not use it as the active contract.
+
+When documents conflict, follow the two current correction taskbooks above.
+
+## Build And Test
+
+```powershell
+npm run build
+npm run test:unit
+npm run test:smoke
+npm run test:mode-b
+npm run test:e2e
+npm test
+```
+
+For changed files, run LSP diagnostics, focused tests, then the full suite. Strict verify, handoff check, module tests, dependency audits, managed-file hashes, root-integrity hashes, and negative install gates are required before closure.
+
+## Real Feishu Boundary
+
+Local generation, strict verification, replay installation, and module tests do not complete real Feishu Level 2. Level 2 remains incomplete until valid `FEISHU_APP_ID`, `FEISHU_APP_SECRET`, `TEST_CHAT_ID`, and `ALLOWED_OPERATOR_OPEN_IDS` are supplied through a secure channel; the long connection is online; real cards are sent and clicked; and sanitized message IDs, screenshots, logs, trace IDs, and verifier sign-off are recorded in `level2_verification_record.md`.

README.md

@@ -47,8 +47,29 @@ node dist/index.js verify generated\image-agent-web-lark --mode embedded-adapter
 node dist/index.js verify generated\image-agent-web-lark-self-hosted --mode self-hosted-runtime --strict
 node dist/index.js evidence generated\image-agent-web-lark
 node dist/index.js handoff generated\image-agent-web-lark
+node dist/index.js install generated\calendar-stock-updater-lark --target C:\path\to\calendar-copy
+node dist/index.js install generated\calendar-stock-updater-lark --target C:\path\to\calendar-copy --apply
 ```
 
+## 结构分析后端
+
+`analyze` 支持 `--backend auto|internal|codegraph`，默认使用 `auto`：
+
+- `internal`：只使用 Code2Lark 内置源码扫描；
+- `auto`：优先尝试用户自行维护的 codegraph 索引；如果 CLI 不可用、索引未初始化、陈旧、不完整或输出无效，则安全回退到 internal，并把 requested / used / fallback 原因写入分析产物；
+- `codegraph`：显式要求新鲜可用的外部索引；条件不满足时直接报错，不静默回退。
+
+Code2Lark 只允许调用以下只读命令：
+
+```text
+codegraph status <repo> --json
+codegraph query route --kind route --path <repo> --json
+```
+
+Code2Lark 不会安装 codegraph，也不会运行 `init`、`sync`、reindex 或其他索引写入操作。外部结果只提供文件、符号和路由等低层结构事实；业务 Profile、能力推断、卡片动作、权限和安装范围仍由 Code2Lark 决定。
+
+calendar-stock-updater 的最终 replay 使用 `--backend auto`，由于目标没有用户维护的新鲜 codegraph 索引，记录结果为 requested=`auto`、used=`internal`、status=`fallback`；分析与后续严格验证正常完成。
+
 ## 交付模式（Delivery Modes）
 
 Code2Lark 的标准输出始终是：
@@ -59,23 +80,69 @@ generated/<target>-lark/
 
 把这个生成目录视为**单一事实来源（source of truth）**：其中包含 manifest、adapter 代码、宿主模块、文档和验证记录。
 
+The canonical MVP package is freshly generated from current schema 0.2 manifests.
+
 ### Mode A：外置宿主 / sidecar / gateway
 
+Mode A is the external host, sidecar, or gateway path. Mode A is a validated deployment-test baseline in the verified `image-agent-web` sample.
+
 Mode A 是**外置宿主**路线。目标服务继续保持自己的生命周期，Code2Lark 生成的宿主在目标服务外部运行，通过 HTTP / CLI / SDK 去调用目标能力。
 
 当前已经验证通过的 `image-agent-web` long-connection 样板，在实际落地上属于 **Mode A**：`feishu-host/` 作为外置 Python 宿主接入飞书，再通过 HTTP 调 `image-agent-web`。
 
 ### Mode B：目标项目内增量宿主模块
 
-Mode B 是**目标项目内增量宿主模块**路线。生成包依然是 source of truth，但可以把其中的宿主模块（如 `feishu-host/`）复制到目标项目仓库里，作为一个增量模块使用。
+Mode B is the target-project embedded host-module path. Mode B is a validated deployment-test baseline in the verified `image-agent-web` sample.
+
+Mode B 是**目标项目内增量宿主模块**路线。生成包依然是 source of truth；标准流程使用显式 `install` 命令把生成包中的闭包安装到目标项目，默认只做 dry-run，只有 `--apply` 会写入。
 
 Mode B 不是重写目标项目业务代码，而是：
-- 最小侵入地迁入宿主模块
-- 保留 `.env`、启动方式、验证方式和交接契约
-- 让目标项目自己承载飞书宿主能力
+- 只写入 `integrations/lark/` 隔离模块
+- 使用模块自己的 `.env.example`、依赖、启动方式、测试和交接契约
+- 不修改目标根 `package.json`、启动脚本、Docker、业务代码或 Web UI
+- 安装前要求目标健康端点在线，并通过生成包契约与托管文件冲突检查
+
+calendar-stock-updater 的两阶段示例：
+
+```powershell
+# 1. 候选包仍位于 generated/，generate 不写目标项目
+node dist/index.js generate out\calendar-stock-updater --out generated\calendar-stock-updater-lark --mode embedded-adapter --host-mode embedded-long-connection
+
+# 2. 默认 dry-run：在线探测、契约校验、冲突检查，零写入
+node dist/index.js install generated\calendar-stock-updater-lark --target C:\path\to\calendar-copy
+
+# 3. 人工审查后显式安装，只写 integrations/lark
+node dist/index.js install generated\calendar-stock-updater-lark --target C:\path\to\calendar-copy --apply
+```
+
+#### calendar-stock-updater 当前状态
+
+当前 calendar Mode B 路线已经完成本地工程闭环：
+
+- 原始 `calendar-stock-updater` 项目保持只读，没有修改根 `package.json`、启动脚本、Docker、业务代码或 Web UI；
+- 安装验证使用独立 replay，只通过 `install --apply` 写入 `integrations/lark/**`；
+- 目标调用仍严格限制为 `GET /api/state`、`POST /api/run` 和 `POST /api/stop`；
+- strict verify 为 32 PASS / 0 WARN / 0 FAIL；Code2Lark 完整测试 41/41、replay 根测试 49/49、安装模块测试 8/8；
+- 真实飞书长连接已成功建立并发送起始卡，真实 `card.action.trigger` 也已到达宿主；
+- 当前真实联调阻塞在 `ALLOWED_OPERATOR_OPEN_IDS`：配置值与回调中的当前应用维度 `operator.open_id` 不一致，因此安全门禁按预期拒绝了操作；
+- 真实 Level 2 尚未完成，仍需修正白名单后重新验证刷新、普通预演、停止流程，并补齐截图、message ID、脱敏日志和签字证据。
+
+安装模块的本地配置位于目标 replay 的 `integrations/lark/.env`。不要把真实值提交到 Git：
+
+```dotenv
+FEISHU_APP_ID=
+FEISHU_APP_SECRET=
+TEST_CHAT_ID=
+ALLOWED_OPERATOR_OPEN_IDS=<current-app-operator-open-id>
+TARGET_BASE_URL=http://127.0.0.1:3069
+```
+
+`ALLOWED_OPERATOR_OPEN_IDS` 是允许操作卡片的飞书用户 `open_id` 白名单，多个值使用英文逗号分隔。`open_id` 是应用维度标识，必须取自同一个飞书应用的 `card.action.trigger` 回调字段 `event.operator.operator_id.open_id`，不能使用手机号、chat id、user_id 或另一个应用下的 open_id。飞书应用、机器人能力、权限和长连接订阅在 [飞书开放平台开发者后台](https://open.feishu.cn/app) 配置。
 
 ### `self-hosted-runtime`
 
+self-hosted-runtime is the generated host module.
+
 `self-hosted-runtime` 是生成出来的宿主模块产物。它当前可以像已验证样板一样**在目标项目外部运行**，未来也可以迁入目标项目内部作为 **Mode B** 的基础宿主模块。
 
 ### `standalone-runtime`
@@ -414,6 +481,6 @@ Code2Lark 负责构建接入包，也可以探测目标服务是否可达；但
 - operator allowlist
 - duplicate-action 去重
 - `image-agent-web` 的真实长连接样板已经完成真人飞书验证
-- `calendar-stock-updater` 已进入 `generic_http_api` 工作流
+- `calendar-stock-updater` 已具备专用业务 Profile 和 dry-run-first Mode B 隔离安装流程；全新 replay 的本地安装、离线阻断、冲突阻断与模块合同已验证；真实长连接、发卡和回调到达已观察，当前需修正当前应用维度的 operator open_id 白名单后继续 Level 2
 
 但 webhook / standalone 的真实 Level 2，以及更多目标项目的真实飞书接入，仍然是后续阶段的工作。