---
name: access-database
description: 通过唯一受控入口查询或修改 muse-example PostgreSQL，并应用可审计 DDL。主会话或 Skill 需要通用数据库访问时使用；专用导入、嵌入和检索仍走各自 Skill，禁止裸连和一次性脚本。
---

# 访问 muse-example 数据库

对应 muse API 面：数据访问层。连接事实与凭据见 [`db/连接信息.md`](../../../db/连接信息.md)。连接实现在共享运行时包 `muse_db`（DSN 锁死 `muse-example`）：本 Skill 提供人和主会话用的 CLI，其它 Skill 与只读看板直接 `from muse_db import connect`，不 import 本目录脚本。

## 用法（仓库根目录执行，python 一律用 `.venv/bin/python`）

```bash
# 查询：卡片式打印（默认最多 50 行、长值截 160 字）
.venv/bin/python .agent/skills/access-database/scripts/db.py query "SELECT id,title FROM muse_content_work"
.venv/bin/python .agent/skills/access-database/scripts/db.py query "SELECT ..." --json      # JSON 数组输出（给脚本消费）
.venv/bin/python .agent/skills/access-database/scripts/db.py query "SELECT ..." --full      # 长值不截断
.venv/bin/python .agent/skills/access-database/scripts/db.py query "SELECT ..." --max 200   # 放宽行数

# 单条写操作（INSERT/UPDATE/DELETE，DELETE 必须带 WHERE）：报影响行数；机械拒绝 DDL/裸删
.venv/bin/python .agent/skills/access-database/scripts/db.py exec "UPDATE ... WHERE ..."

# 参数化写操作：SQL 用 %s 占位，参数走服务端绑定（防注入；大内容不拼命令行）；同样禁止 DDL/裸 DELETE
.venv/bin/python .agent/skills/access-database/scripts/db.py execparams "INSERT INTO example_raw_content(kind,content_sha256,content) VALUES (%s,%s,%s)" --param response --param <sha> --param "短文本"
# 大对象（raw 全文）经 stdin 传 JSON 数组（避开 shell 转义 / ARG_MAX）：
.venv/bin/python .agent/skills/access-database/scripts/db.py execparams "INSERT ... VALUES (%s,%s)" --stdin < params.json    # params.json = ["<sha>", "<完整全文>"]

# SQL 文件应用（DDL 唯一入口）：整文件一个事务，失败全回滚；先落 db/ddl/ 再 apply
.venv/bin/python .agent/skills/access-database/scripts/db.py apply db/ddl/91-example实验私货.sql

# 表清单+活行数（deleted=FALSE 计数，无 deleted 列的表计全行）
.venv/bin/python .agent/skills/access-database/scripts/db.py tables

# A3 种子：23 型 YAML → meta 表行（幂等可重跑；字段改动=改 YAML 后重跑）
.venv/bin/python .agent/skills/access-database/scripts/seed_schemas.py
```

## 红线

- **只连 `muse-example`**：DSN 锁死在 `muse_db` 内；严禁另拼连接串去碰共享 PG 上的 muse_local / muse_slice_live / *_test。
- 软删约定照主仓：删除=UPDATE `deleted=TRUE`，不物理删（example_* 表同样遵守）。
- 批量导入/嵌入等专用写路径由 `import-book`/`embed-knowledge` Skill 封装（内部同走 psycopg 直连），本 Skill 承担通用查改；DDL 只经 `apply` 文件入口。
- 建表/改表先落 `db/ddl/` 文件再 `apply`，不敲一次性 DDL——文件即审计；`exec`/`execparams` 机械拒绝 DDL 与无 WHERE 的 DELETE。
- 大对象写入（raw 全文等）走 `execparams` 参数化通道（大内容经 stdin JSON），不得把大内容拼进 `exec` 的 SQL 字符串（shell 转义 + ARG_MAX）；参数化绑定同时防 SQL 注入。

## 元数据驱动

库内 `muse_meta_schema` / `muse_meta_field` / `muse_meta_visibility_policy` 是 23 型结构本体的权威行（A3 起）；拆书与抽取的字段合同一律 `query` 读库取，不再读 `meta/schemas/` YAML（YAML 退为设计稿与种子来源）。

## 数据边界

- 读写范围限于本 Skill 合同声明的表/文件；失败整体回滚，不留半写入状态。
- 模型调用走统一网关；raw 证据由 `record-run-evidence` 归档。

## 输出

- 面向当前任务的可执行判断、检查清单或改写建议（Markdown 结构化段落）。
- 不直接落库、不代替 `write-next-chapter` / `decide-candidate` 写 Canonical。

## 复利合同

- **模式 C（平台底座）**：`lifecycle=platform`，D8 不适用；不登记创作经验 `example_lesson`。本 Skill 只提供受控 DB 入口，供上游绑定 `run_id`/证据。