# Forge

**Repository Path**: gh-mirrors/Forge

## Basic Information

- **Project Name**: Forge
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Forge

[![CI](https://github.com/shisuidata/Forge/actions/workflows/ci.yml/badge.svg)](https://github.com/shisuidata/Forge/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

> **面向 Data Agent 的开源可信数据运行时：让 AI 辅助的数据查询可约束、可审核、可执行、可追溯。**

Forge 位于上游 Agent 与数据库之间。它接收 Direct SQL 或受约束的 Forge JSON 候选，通过 Registry、确定性 SQL 编译、只读与权限校验、人工审核、Evidence 和 Audit 降低静默错误。它不是只把自然语言转成 SQL 的 wrapper，也不把“模型生成了 SQL”等同于“查询可信”。

[English](README.md) · [贡献指南](CONTRIBUTING.md) · [文档索引](docs/README.md)

## 30 秒理解 Forge

| 普通 Text-to-SQL 路径 | Forge 当前路径 |
|---|---|
| 模型直接生成并执行开放 SQL | 候选先进入受约束、可拒绝的保障流程 |
| Prompt 同时承担语义、语法和安全 | Registry 管语义，编译器管转换，运行时管校验与执行 |
| 失败通常只有“SQL 报错” | 保留输入类型、SQL hash、版本、失败阶段和 Evidence |
| 结果正确性依赖单次模型表现 | 用可复现 benchmark 和 regression 迭代，不承诺开放世界 100% 正确 |

**当前已有的核心能力：**

- Forge JSON 受约束中间表示与确定性 SQL 编译；
- Direct SQL / Forge JSON 统一候选、QueryRun 审核和执行链；
- 版本化、非执行的 Evaluate API/CLI，以及持久 suite、manifest、回放与 Regression gate；
- 版本化 Enforce API/CLI，将 Principal、Purpose、Task、Resource Scope、Policy、Assurance、Registry 与 hash-bound 人工审批绑定进 QueryRun；
- 版本化 Explain API/CLI，从同一 QueryRun 投影实际 SQL/结果、持久 Registry 语义、治理信息、Evidence、lineage、integrity 与显式限制；
- Registry 结构与语义约束、关系和粒度校验；
- 只读 SQL、字段/表范围、审批 hash、超时和结果上限；
- SQLite、PostgreSQL、MySQL 的自动化兼容性检查；
- 可回放的准确率 Benchmark、Exact Result 比较和失败诊断。

> **项目状态：early-stage，持续维护。** 当前适合评估、贡献和带人工审核/只读账号的受控部署，不代表功能完备或高可用。最新完整 Structured GPT-5.6 BIRD 运行封存成绩为 **Forge EA 57.4% / Direct SQL 62.8%**；随后对**同一批候选**修复编译器并离线重评为 **62.6% / 62.8%**，不是新生成成绩，也不证明 Forge JSON 的准确率优势。详见 [当前状态](docs/current-project-state.md)、[基准规范](docs/benchmarks.md) 与 [每轮报告索引](docs/README.md)。

**升级注意（2026-09-07）：** 共享Assurance已升为`query-assurance-v10`，按SQL作用域校验真实物理来源，不能借嵌套同名CTE绕过表权限。当前扁平Registry未建模的schema/catalog限定来源失败关闭。旧v9 QueryRun审批返回`assurance_revision_drift`，需重新prepare和人工审核，不原地升级旧证据。见[版本验证报告](docs/archive/engineering/release-verification-2026-09-07.json)。

---

## 快速开始

### Public Golden Path

```bash
git clone https://github.com/shisuidata/Forge
cd Forge
bash scripts/bootstrap-dev.sh
source .venv/bin/activate
forge quickstart
```

这一条命令就是完整的公开 Trust Runtime 路径：启动隔离的本地 Forge 服务与 SQLite 数据源，用 **Direct SQL** 调用 `Evaluate`，在 `Enforce` 阶段展示实际 SQL 并等待人工批准，批准后执行，再从同一个 QueryRun 调用 `Explain`，最后验证 Dashboard 投影。无需 API Key、LLM、Embedding、Pi、Forge JSON、已有数据库或 `.env`。

预期证据：第一条 `Evaluate` 请求以 `assurance/readonly_violation` 拒绝写 SQL；只读请求的精确结果对比通过；`Enforce` 返回两行并明确标记行数上限截断；`Explain` 返回 `integrity=verified`、七类 Evidence 与显式限制；Dashboard 显示同一个 QueryRun ID；`run_receipt.receipt_hash` 为脱敏回执提供稳定校验和。

```bash
# 保持隔离服务运行，并打印可直接打开的 Dashboard 地址。
forge quickstart --serve

# CI 非交互输出；仅因命令使用本地合成数据而适合自动批准。
forge quickstart --yes --json

# 保留数据库、QueryRun、服务日志和证明摘要。
forge quickstart --yes --workdir .forge/quickstart-proof
```

`--yes` 只是 Demo 便利参数。真实 Enforce 部署仍必须使用已认证的创建者/审批者分离，并提交匹配的不可变 review hashes。
如果这是独立试跑，请通过 [Quickstart adoption report](https://github.com/shisuidata/Forge/issues/new?template=quickstart-adoption.yml) 提交脱敏后的 `run_receipt`、fresh-clone setup time、第一处失败或困惑，以及你对输出边界的理解。Forge 不发送遥测。校验和只用于发现回执漂移和去重，不是身份证明；GitHub 作者身份提供公开来源。

### 完整自然语言问数 Demo（可选）

下面的宽口径 NLQ Demo 需要 LLM 与 Embedding 配置，不属于 Trust Runtime Golden Path：

```bash
cp .env.example .env
bash scripts/demo-setup.sh
uvicorn main:app --host 0.0.0.0 --port 8000
```

**Docker 开发方式（自带 PostgreSQL，热重载）：**

```bash
docker compose up
# 访问 http://localhost:8000/admin
```

**生产交付方式：**

```bash
cp .env.production.example .env.production
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build
forge doctor --profile prod
bash scripts/production-smoke.sh
```

生产部署必须使用数据库只读账号，并确认 `/health/readiness` 无 `fail` 项。详见 [生产交付部署说明](docs/production-deployment.md)。

**接入自己的数据库：**

```bash
# 修改 .env 中的 DATABASE_URL，然后同步 schema
forge sync --db postgresql://user:pass@host/db
# 或写入指定 Registry 路径
forge sync --db "$DATABASE_URL" --out registry/data/schema.registry.json
```

**使用火山方舟 Ark（OpenAI 兼容接口）：**

```env
LLM_PROVIDER=openai
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=doubao-seed-2-1-pro-260628
LLM_API_KEY=你的火山方舟 API Key
```

**运行测试：**

```bash
# 编译器 + API 测试（本地，无需服务运行）
pytest tests/ -v

# Playwright E2E 测试（需服务运行）
pip install playwright && playwright install chromium
FORGE_BASE_URL=http://localhost:8000 pytest tests/test_e2e.py -v
```

---

## 评测已有 Agent 输出

公开版本化接口 `POST /api/v1/evaluate` 使用同一请求信封接收 Direct SQL 或 Forge JSON，执行候选契约、Registry、范围、只读和结果契约校验。它**不会执行 SQL**，也不会授予执行权限；`allowed_tables` 只是本次评测条件，不是访问授权。

创建 `evaluation.json`：

```json
{
  "schema_version": 1,
  "question": "返回数字 1",
  "dialect": "sqlite",
  "candidate": {
    "kind": "direct_sql",
    "sql": "SELECT 1 AS value",
    "producer_revision": "example-agent-v1"
  },
  "expected_result": {"columns": ["value"], "rows": [[1]]},
  "actual_result": {"columns": ["value"], "rows": [[1]]}
}
```

通过 CLI 或 curl 调用：

```bash
export FORGE_BASE_URL=http://127.0.0.1:8000
# 仅在开启 API 鉴权时设置 FORGE_API_KEY。
forge evaluate evaluation.json

curl --fail-with-body -sS "$FORGE_BASE_URL/api/v1/evaluate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $FORGE_API_KEY" \
  --data @evaluation.json
```

通过 Python 调用：

```python
import json
import os

import httpx

request = json.load(open("evaluation.json", encoding="utf-8"))
headers = {"X-API-Key": os.environ["FORGE_API_KEY"]} if os.getenv("FORGE_API_KEY") else {}
response = httpx.post(
    os.getenv("FORGE_BASE_URL", "http://127.0.0.1:8000") + "/api/v1/evaluate",
    json=request,
    headers=headers,
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

通过时返回 `policy.verdict: "allow_review"`、不可变 lineage hash 和响应内 `evidence_refs`；失败时仍返回同一信封，并提供有界的 `failure.stage` 与 `failure.code`，CLI 以非零状态退出。评测 Forge JSON 时，将 `candidate` 替换为 `{"kind":"forge_json","forge_json":{...}}`。

需要持久评测集合、可复算运行清单和 Regression release gate 时，使用仓库内公开样例：

```bash
# 持久化集合及其原始 case outcomes。
forge evaluate examples/evaluation-suite-v1.json --suite

# 回放不可变集合、对比基线，或导出运行清单。
forge evaluate --suite-revision "sha256:<suite-revision>" --baseline-run "evr_<baseline>"
forge evaluate --run-id "evr_<run-id>"
```

`evaluation-suite-v1` 记录数据集、producer/model、Prompt、检索、重试和超时版本；持久化的 `evaluation-run-manifest-v1` 继续绑定 evaluator、metric、候选契约、Assurance、Policy、Registry、dialect、原始 case outcomes 和可复算聚合。默认 release gate 不允许新增失败或通过率下降。数据集、case selection、预期评测基准、Policy、evaluator、Registry 或 dialect 变化时标记为 `not_comparable` 并失败关闭；producer/model/Prompt 版本允许变化，因为它们正是被比较变量。

## 执行已审核的查询

`POST /api/v1/enforce/query-runs` 只准备受治理 QueryRun，创建时绝不执行。请求遵循 [`enforce-query-request-v1`](agent/contracts/enforce-query-request-v1.schema.json)，将候选与 Principal、Purpose、Task、Resource Scope、Policy、Assurance、Registry revision 和只读数据源绑定。Human 直接调用时由本人承担责任；Agent/Service 调用必须提供唯一有效的 [Delegated Mandate](agent/contracts/delegated-mandate-v1.schema.json)，并与 actor、accountable human、task、purpose、capability 和 scope 完全匹配。

```bash
# 仅准备；返回 status=review_required 和不可变审核 hashes。
forge enforce enforce-request.json --idempotency-key prepare-001

# 使用创建时的凭证回读同一个受治理 QueryRun。
forge enforce --run-id "qr_<query-run-id>"

# 使用独立 reviewer credential 提交审核 hashes，并且只执行一次。
FORGE_API_KEY="$FORGE_REVIEWER_API_KEY" forge enforce approval.json \
  --approve "qr_<query-run-id>" \
  --idempotency-key approve-001
```

`approval.json` 遵循 [`enforce-query-approval-v1`](agent/contracts/enforce-query-approval-v1.schema.json)：复制准备响应中的 `sql_hash`、`assurance_report_hash` 与 `enforcement_context_hash`，并标明承担责任的 Human reviewer。开启 API 鉴权时，普通创建/读取凭证放入 `AUTH_API_KEYS`，独立审批凭证放入 `ENFORCE_REVIEWER_API_KEYS`。Policy、Registry、candidate、授权上下文、scope、approval 或只读凭证发生 drift 时均失败关闭。响应遵循 [`enforce-query-response-v1`](agent/contracts/enforce-query-response-v1.schema.json)，返回有界失败码，不泄漏原始数据库错误。

该 v1 路径只覆盖 Direct SQL/Forge JSON 的查询准备、审批和执行，不代表完整 IAM、生产部署或非查询 Action 的治理已完成。

## 解释受治理 QueryRun

`GET /api/v1/explain/query-runs/{query_run_id}` 为任意受治理 QueryRun 返回稳定的 [`explain-query-response-v1`](agent/contracts/explain-query-response-v1.schema.json) 投影。它使用创建凭证，并与 Enforce 读取同一个 QueryRun 真相源：

```bash
# 开启鉴权时，FORGE_API_KEY 必须是创建该 QueryRun 的凭证。
forge explain "qr_<query-run-id>"

curl --fail-with-body -sS   -H "X-API-Key: $FORGE_API_KEY"   "$FORGE_BASE_URL/api/v1/explain/query-runs/qr_<query-run-id>"
```

响应包含候选、实际审核 SQL、有界结果或失败、持久化表列描述、数据源与资源范围、Principal/Policy/Approval、Assurance gates、版本/hash lineage、确定性 Evidence 引用与限制。来源上下文、审批和完成结果均受 hash 约束；篡改会返回有界 Explain 错误并失败关闭。缺少这些锚点的历史 QueryRun 返回 `integrity.status: "partial"` 并逐项标明未验证组件，不伪造证明。

每份解释都披露适用的认识论和运行边界，包括实时执行没有固化数据库 snapshot，以及 Registry 绑定和确定性门禁不能证明开放世界业务语义正确。Explain 不公开凭证 hash、内部存储结构或原始数据库错误。

---

## 工作原理

```mermaid
flowchart LR
    NL["自然语言"]

    subgraph forge["Forge 管道"]
        direction TB
        REG["Registry<br/>结构层 + 语义层"]
        RETRIEVER["SchemaRetriever<br/>向量检索 / BM25 降级"]
        LLM["LLM<br/>Structured Output"]
        JSON["Forge JSON<br/>有约束的中间表示"]
        COMPILER["确定性编译器"]
        SQL["SQL"]
    end

    DB["数据库"]
    RESULT["结果集"]

    NL --> RETRIEVER
    REG --> RETRIEVER
    RETRIEVER -->|"top-k 相关表"| LLM
    LLM --> JSON
    JSON --> COMPILER
    COMPILER --> SQL
    SQL --> DB
    DB --> RESULT
```

自然语言经 Registry 语义注入后，由 LLM 生成结构化的 Forge JSON，再由确定性编译器翻译为 SQL。在 Provider 严格执行动态 JSON Schema 的字段上，非法候选可在生成阶段被阻止；表达式透传、兼容降级路径、业务口径和算法选择仍需校验、审核与测试。用户审核的 SQL 和执行的 SQL 是同一份。

从产品价值、核心原理到生产落地的系统讲解，见 [Forge 完整架构教材](docs/architecture-course/index.md)；快速参考见 [工作原理与 DSL 能力](docs/how-it-works.md)。

---

## 当前状态

| 证据 | Forge Official EX / EA | Direct SQL Official EX / EA | 口径 |
|---|---:|---:|---|
| DeepSeek V4 Flash，完整生成 | 227/500（45.4%） | 282/500（56.4%） | 历史运行，不是最新成绩 |
| GPT-5.6，文本生成 | 266/500（53.2%） | 311/500（62.2%） | 完整配对生成 |
| GPT-5.6，Structured Tool 原封存 | 287/500（57.4%） | 314/500（62.8%） | 原运行判定保留 |
| 同一批 Structured 候选，Compiler 离线重评 | 313/500（62.6%） | 314/500（62.8%） | 不是重新生成 |

最后一行 Forge-only 22 / Direct-only 23，双侧 exact p=1.0，不支持 Forge JSON 准确率优势；原生成 Forge 仍多59.57% tokens、51.69%平均生成时间。比较器v2修正后的 Contract 为284/500与294/500，Official EX不变，两种指标不得混算。

额外一次DeepSeek复验每臂只有78份候选、422份缺失，并发生额度/余额失败，不构成第四轮有效500题运行。历史40题、自有LLM Judge和Spider2不同分母/重试策略的结果保留在[基准历史](docs/benchmarks.md)，不能拼成排行榜。

### 本次迭代与逐轮报告（2026-09-07）

- 可复用的BIRD冻结、预检、验证、原候选重放、配对比较和全请求质量指标；协议绑定源码、数据、模型、上下文及调用预算，漂移失败关闭。
- Compiler局部别名/CTE绑定和共享Assurance边界维护；不猜缺失导出、不自动补列或按Gold返修。
- 分母范例16次对照：Forge EX/Contract 2/4→3/4，但正确对照回退，不采纳。
- CTE接口范例16次对照：Forge两指标3/4→3/4，md-199新增正确、md-079回退；Direct两指标3/4→2/4，其输入未变，波动不能归因于Forge范例。总67367 tokens；Forge每正确答案成本+13.11%、四次采样生成P95+41.53%，门槛失败，不启用。
- 日期、粒度、取值上下文仍默认off。已曝光BIRD为R回归集，小样本D与隔离S不代表独立H；外部采用门禁仍未通过。

[逐轮报告索引](docs/README.md)保留准备、生成、离线修复、负结果和未完成实验；[早期运行汇总](docs/archive/benchmarks/benchmark-historical-runs-2026-09-07.json)与[最新CTE报告](docs/archive/benchmarks/benchmark-luna-cte-interface-2026-09-07.json)分别标明来源和限制。[公开处理清单](docs/archive/engineering/report-publication-2026-09-07.json)记录原件/公开副本hash；本机路径和个人联系样本脱敏，分数、成本与失败状态不改。原始运行数据库、Provider会话与第三方数据集不随仓库分发，本地工件路径不等于公开下载地址。

### 已落地功能

| 功能 | 状态 |
|---|---|
| Web UI（Chat + 12 个 Admin 页面 + Dashboard 概览） | ✅ |
| SQL 审核编辑（生成后可修改 SQL 再执行） | ✅ |
| 查询结果导出（CSV / JSON，中文 BOM 兼容） | ✅ |
| 认证鉴权（Cookie session + API Key） | ✅ |
| 多租户基础（user → team 映射；org/team/user 仍在完善） | ✅ 基础能力 |
| 数据权限（team 级别表可见性 ACL + 无权限提示） | ✅ |
| PostgreSQL 支持（SQLite 零改动切换） | ✅ |
| 三层记忆系统（EMS / SMP / WMB） | ✅ |
| Pipeline 引擎（分析 / 可视化 / 报告） | ✅ 代码路径；需客户域验收 |
| 飞书 Bot（流式卡片 + 按钮回调） | ✅ |
| 五通道知识收集（RSS / URL / 文档 / 对话 / 手动） | ✅ |
| 文档导入（上传 .txt/.md → LLM 提取 → 确认入库） | ✅ |
| 自动化测试（API / compiler / executor / lint / docs / audit / feedback） | ✅ |
| 部署就绪检查（`/health/readiness` + `forge doctor`） | ✅ |
| 生产部署包（Dockerfile / compose.prod / env 模板 / 部署文档） | ✅ |

---

## 项目结构

```
forge/
  ├── schema.json          — Forge DSL 格式定义（JSON Schema）
  ├── compiler.py          — 确定性编译器：Forge JSON → SQL
  ├── retriever.py         — Schema 向量检索器（四层召回 + ACL 过滤）
  ├── executor.py          — SQL 执行器
  ├── lint.py              — 业务/字段/结果契约检查
  ├── cache.py             — 查询缓存（精确 + 模糊匹配）
  ├── chart.py             — 图表生成（ECharts）
  └── cli.py               — CLI 入口（evaluate / enforce / explain / compile / sync / doctor）

agent/
  ├── agent.py             — Agent 调度（查询 / 指标定义 / 缓存反馈）
  ├── llm.py               — LLM 客户端（RAG + ACL + 约定注入）
  ├── pipeline.py          — Pipeline 引擎（分析 / 可视化 / 报告）
  ├── db.py                — 数据库抽象层（SQLite / PostgreSQL）
  ├── tenant.py            — 多租户（org / team / user / ACL）
  ├── knowledge.py         — 五通道知识收集框架
  └── memory/
      ├── ems.py           — Episodic Memory Store（对话历史）
      ├── smp.py           — Semantic Memory Pool（业务知识）
      └── wmb.py           — Working Memory Buffer（当前上下文）

web/
  ├── router.py            — FastAPI 路由（Web UI + API + execute-raw）
  ├── auth.py              — HMAC-SHA256 Cookie + API Key 认证
  └── templates/           — Jinja2 模板（Chat + Dashboard + 11 个 Admin 页面）

registry/
  ├── sync.py              — forge sync：直连数据库生成结构层
  ├── staging_sync.py      — 用户确认规则合并入 Registry
  └── data/                — 生产 Registry 路径（schema / metrics / disambiguations / conventions）

scripts/
  └── seed_mock_data.py    — Mock 数据填充（团队/用户/审计/会话/知识）

tests/
  ├── conftest.py          — 共享 fixtures（app / client / auth_client）
  ├── test_compiler*.py    — 编译器单元测试（118 个用例）
  ├── test_api.py          — API 端点测试（26 个用例）
  ├── test_e2e.py          — Playwright E2E 测试（22 个用例）
  ├── test_docs_links.py   — 公开文档本地链接检查
  ├── accuracy/            — 自有 40 题基准（当前推荐 Method AI）
  └── spider2/             — Spider2-Lite SQLite 子集（123 题）
```

---

## 文档

| 文档 | 内容 |
|---|---|
| [当前项目状态](docs/current-project-state.md) | 当前产品定义、阶段、门禁、未关闭验收项与 OMP 继续开发入口 |
| [文档导航](docs/README.md) | 区分当前事实、稳定约束、主动计划与历史材料 |
| [完整架构教材](docs/architecture-course/index.md) | 从可信问数原理、核心技术优势到实战与生产架构 |
| [架构设计](docs/architecture.md) | 系统整体架构与模块职责的精简入口 |
| [产品北极星](docs/product-north-star.md) | Forge 为什么存在、服务谁，以及正确性、共识、数据事实与产品边界的长期指导 |
| [产品设计与阶段路线重建提案](docs/product-design-roadmap-2026-08-25.md) | Human Control Plane、Agent Data Runtime、产品对象、信息架构与长期阶段方向 |
| [短期 Product Spine 历史计划](docs/archive/plans/short-term-product-spine-plan-2026-08-25.md) | SP0–SP5 已完成实施与验证记录；仅作历史溯源，不是当前待办 |
| [Product Spine SP5 集成门禁证据](docs/archive/engineering/product-spine-sp5-evidence-2026-08-25.md) | 真实 Pi/Forge/Report 三连 Golden Journey、restart/idempotency/offline、Atlas candidate 与失败关闭反证 |
| [Product Projection v1 Contract](docs/product-projection-contracts.md) | Conversation、Task、Action、Workspace、Report 的版本化只读边界、状态、bounds、redaction 与 SP1 入口 |
| [产品公理](docs/product-axioms.md) | 以第一性原理约束身份、证据、协同、记忆、成本与可信行动 |
| [AI Native 企业长期论证](docs/ai-native-enterprise-thesis.md) | Data Agent、组织协同、统一记忆、企业 AI Infra 的论证、反证与待验证假设 |
| [产品方向与架构复审](docs/archive/engineering/product-direction-architecture-review-2026-08-24.md) | 按产品公理审核当前实现、四平面缺口、目标架构与分阶段建议 |
| [企业演进主动计划](docs/forge-enterprise-evolution-plan.md) | 唯一主动计划；当前阶段为 S0 Design Partner / Problem Baseline |
| [需求池](docs/requirements-pool.md) | 新需求的澄清、评估、接受、延期、拒绝、计划与验证记录 |
| [M0 Governance Contract 评审](docs/archive/engineering/governance-contract-review-2026-08-24.md) | 跨 Contract 语义、Threat Model、迁移/回滚与 M1A 前置结论 |
| [工作原理与 DSL 能力](docs/how-it-works.md) | 执行流程详解、DSL 特性表、Schema RAG |
| [基准测试详情](docs/benchmarks.md) | 版本演化、跨模型 EA 对比、Spider2 结果 |
| [设计哲学与工程洞察](docs/philosophy.md) | 核心哲学、工程经验、开放问题 |
| [商业化就绪清单](docs/commercial-readiness.md) | 当前商业化差距、已补齐的安全/审计能力、PoC 到正式交付路线 |
| [商业化推进计划](docs/commercialization-plan.md) | P0/P1/P2 优先级、准确率闭环、PoC 到正式交付判定标准 |
| [兼容性矩阵](docs/compatibility-matrix.md) | 数据库、数据仓库、Agent 入口、LLM 服务的支持边界 |
| [客户 PoC 执行手册](docs/poc-playbook.md) | 客户域 golden questions、failure triage 和交付物 |
| [外部 Agent 集成边界](docs/agent-integration.md) | MCP / OpenAI Agents / Claude Desktop 等外部入口的 prepare-query 只读边界 |
| [交付前综合评估](docs/archive/engineering/delivery-assessment-2026-05-07.md) | 业务板块、文档、目录、工作流、三轮测试和交付优化方案 |
| [生产交付部署说明](docs/production-deployment.md) | 生产 compose、env、只读数据库账号、readiness、运维建议 |
| [DSL 形式化语义](docs/dsl-semantics.md) | DSL 的形式化定义 |
| [构建你的语义库](docs/registry.md) | Registry 结构层 + 语义层三文件详解，从零构建指南 |
| [飞书 Bot 部署](docs/feishu-setup.md) | 飞书集成配置 |

---

## 开发日志

真实的建造记录，包括走错的路、自我怀疑的时刻，和偶尔出现的顿悟。

| 篇 | 日期 | 主题 |
|---|---|---|
| [Day 0 · 开发实录](docs/devlog/forge-dev-story.md) | 2026-03 | 为什么做这件事；错误分类；核心洞见的形成过程 |
| [Day 1 · 历史债 / 地面泥潭](docs/devlog/day1_2026-03-15.md) | 2026-03-15 | SQL 的设计哲学、四层召回演进、飞书 Bot 工程坑、SQL 缓存双阶段反馈 |
| [Day 2 · CROSS JOIN / HAVING 别名 / EA 95%](docs/devlog/day2_2026-03-16.md) | 2026-03-16 | CROSS JOIN 标量 CTE 模式、HAVING alias 展开修复、DeepSeek strict tool calling 实验、M/O/N 三组 EA 基准 |
| [Day 3 · 工程稳固 / 产品门面 / 连锁故障](docs/devlog/day3_2026-03-18.md) | 2026-03-18 | Session 持久化、编译器拆分、飞书 Bot 四层连锁故障、demo 向导、forge config CLI |
| [Day 5 · 先看自己错没错 / 三层系统优化](docs/devlog/day5_2026-03-19.md) | 2026-03-19 | 5 处设计缺陷修复、编译重试对齐、约定 lint 程序化验证、LAG 示例补全、M2.7 EA 72.5% |
| [Day 6 · 从原型到产品](docs/devlog/day6_2026-03-25.md) | 2026-03-25 | PostgreSQL 支持、HMAC 认证、数据权限 ACL、Pipeline E2E、Web Admin 完整落地、EA 70.0% |
| [Day 7 · 准确率回炉 / TopN lint](docs/devlog/day7_2026-05-05.md) | 2026-05-05 | 测试口径拆分、Z.AI GLM-5.1 接入受阻、DeepSeek single-run EA 55.0%→65.0%、TopN lint/prompt 优化 |
| [Day 8 · 把准确率问题重新工程化](docs/devlog/day8_2026-05-06.md) | 2026-05-06 | 面向博客发布的阶段总结：测试分层、GLM-5.1 接入受阻、DeepSeek EA 55.0%→65.0%、TopN 错误形式化为 lint |

---

## 参与维护

贡献入口与复现要求见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。[`shisuidata/Forge`](https://github.com/shisuidata/Forge) 是项目主仓库，由 [`shisuidata`](https://github.com/shisuidata) 组织维护；[`rockythink`](https://github.com/rockythink) 是组织管理员和主要维护者。历史提交中原 `shisuidata` 个人账号现为 [`shisuidata-legacy`](https://github.com/shisuidata-legacy)，仅保留历史归属，不再参与项目维护。

## License

Forge 使用 [Apache License 2.0](LICENSE)。

## 官网

`website/` 是 Forge 的 Astro + Starlight 对外站点，用于承载快速开始、概念说明、基准测试和商业化 PoC 叙事：

```bash
cd website
npm install
npm run build
```