22 KiB

Raw Blame History

给 Codex 的项目初始化说明 v0.1

项目暂定名：

model_library_mvp

中文名：

认知模型库 / 模型管理子系统 MVP

0. 当前任务

请初始化一个 file-first 的模型库 MVP 工程。

当前不是开发完整产品，不是做前端后台，不是做商业平台，而是为后续“问题回答子系统”准备一个可维护、可追溯、可调用、可测试的核心模型资产底座。

本次初始化任务的重点是：

1. 创建清晰的项目 README
2. 创建 AGENTS.md 项目规则
3. 创建 docs/ 下的规则类文档
4. 建立目录结构
5. 明确后续开发约束
6. 暂不实现复杂功能

请不要直接进入大规模编码。先把项目说明、工程边界、目录结构和规则文档建好。

1. 项目定位

1.1 一句话定义

本项目是一个 file-first 的认知模型库 MVP，用于把核心认知模型整理成：

来源可追溯
结构可校验
系统可调用
边界可检查
误用可测试
后续可扩展

的模型资产。

第一阶段只用两个样板模型验证工程结构：

1. QPI 问题定性模型
2. 思想考古模型

1.2 项目在整体产品中的位置

整体产品未来包含两个子系统：

1. 模型管理子系统
2. 问题回答子系统

当前项目只做第一个子系统的 MVP：

模型管理子系统 MVP

它的目标不是让用户在界面里管理模型，而是为后续问题回答系统提供可调用的模型库。

后续问题回答系统会基于这些模型完成：

输入问题
→ 选择合适模型
→ 多棱镜分析
→ 冲突汇总
→ 综合洞察输出

但当前阶段不实现完整问题回答系统。

2. 第一使用者

本项目第一使用者是项目所有者本人。

不是面向外部用户，不考虑多人协作，不考虑权限系统，不考虑 SaaS 化，不考虑收费，不考虑公开平台。

因此，第一版应该优先考虑：

结构清楚
维护简单
本地可读
文件可迁移
规则可扩展
便于 ChatGPT / CCRA 与 Codex 交接

不要过早做复杂后台、数据库和用户系统。

3. 当前 MVP 验证命题

第一阶段要验证的不是“能否管理 100 多个模型”，而是：

少量核心认知模型，能否被整理成结构化、可追溯、可调用、可测试的模型资产。

当前只验证两个模型：

QPI
思想考古

如果这两个模型的结构稳定，再扩展到 5 个、8-10 个核心模型。

4. 当前必须做的事情

请初始化以下内容：

README.md
AGENTS.md
docs/PROJECT_BRIEF.md
docs/DATA_CONTRACT.md
docs/WORKFLOW.md
docs/DECISIONS.md
docs/NON_GOALS.md
docs/HANDOFF_TEMPLATE.md
schemas/
models/
cards/
sources/
tests/
selector/
scripts/
reports/

当前可以创建空目录或占位文件，但 README 和 AGENTS.md 必须写清楚项目规则。

5. 当前不要做的事情

本阶段明确不要做：

完整前端后台
数据库接入
向量数据库
复杂 RAG
用户系统
权限系统
计费系统
多人协作
自动从全部文章中抽取模型
完整知识图谱
公开平台
完整问题回答系统
大规模 LLM Agent 编排
复杂 UI

也不要把项目做成通用知识库系统。

本项目不是普通知识库。它是认知模型资产库。

6. 推荐目录结构

请按以下结构初始化：

model_library_mvp/
  README.md
  AGENTS.md

  docs/
    PROJECT_BRIEF.md
    DATA_CONTRACT.md
    WORKFLOW.md
    DECISIONS.md
    NON_GOALS.md
    HANDOFF_TEMPLATE.md

  schemas/
    README.md
    model_card.schema.json
    source_article.schema.json
    source_excerpt.schema.json
    regression_case.schema.json

  models/
    README.md
    qpi.model.json
    intellectual_archaeology.model.json

  cards/
    README.md
    qpi.card.md
    intellectual_archaeology.card.md

  sources/
    README.md
    source_articles.json
    source_excerpts.json

  tests/
    README.md
    qpi.regression.json
    intellectual_archaeology.regression.json

  selector/
    README.md
    selection_rules.json
    selector_examples.json

  scripts/
    README.md
    validate_models.py
    validate_sources.py
    validate_tests.py
    run_selector_demo.py

  reports/
    README.md
    validation_report.md
    extraction_notes.md

如果当前暂不实现 Python 脚本，可以先创建占位 README，说明后续脚本用途。

7. README.md 应包含的内容

请在根目录 README.md 中写入以下结构。

# model_library_mvp

## 1. Project Definition

This project is a file-first MVP for a cognitive model library.

It turns core cognitive models into structured, traceable, callable, and testable model assets.

The first version validates the workflow with two sample models:

- QPI
- Intellectual Archaeology

## 2. What This Project Is

This project is:

- A model asset library
- A model card system
- A source evidence index
- A regression test container
- A minimal model selection demo
- A foundation for a future question-answering / cognitive processing system

## 3. What This Project Is Not

This project is not:

- A full model management platform
- A public SaaS product
- A user-facing application
- A complete knowledge graph
- A full RAG system
- A commercial platform
- A multi-user collaboration system
- A complete question-answering system

## 4. Current MVP Goal

The current MVP tests whether a small number of core cognitive models can be represented as:

- Human-readable model cards
- Machine-readable JSON model specs
- Source article records
- Source evidence excerpts
- Regression test cases
- Minimal selector inputs and outputs

## 5. First Sample Models

### QPI

QPI is a routing model that classifies a user input as:

- Question: lack of information
- Problem: lack of path or method
- Issue: lack of stability, consensus, or dynamic balance

### Intellectual Archaeology

Intellectual Archaeology is a deep modeling model that analyzes a topic through multiple depth layers, from surface application to mechanism, purpose, human capability, and philosophical assumptions.

## 6. Repository Structure

Explain the directory structure here.

## 7. Data Format

The project uses JSON as the machine-readable source format.

Markdown files are used for human-readable model cards and documentation.

## 8. Validation

All model JSON files should eventually pass schema validation.

Validation should check:

- Required fields
- Enum values
- Unique model IDs
- Source article references
- Source evidence references
- Regression test references

## 9. Minimal Selector

The selector is not a full AI system.

It is a simple demo that recommends candidate models based on:

- Trigger keywords
- Input type match
- Negative triggers
- Pipeline position
- Selection priority

## 10. Development Principles

- Keep the MVP small.
- Prefer files over databases.
- Prefer explicit schema over implicit conventions.
- Prefer traceability over automation.
- Prefer testability over expressive writing.
- Do not expand to many models before the sample models are stable.

## 11. Current Status

Initial project setup.

## 12. Next Steps

1. Confirm directory structure.
2. Confirm schema files.
3. Add QPI model JSON.
4. Add Intellectual Archaeology model JSON.
5. Add human-readable model cards.
6. Add source records and evidence excerpts.
7. Add regression cases.
8. Add validation scripts.
9. Add minimal selector demo.

8. AGENTS.md 应包含的内容

请在根目录创建 AGENTS.md，用于约束 Codex 后续工作。

建议内容如下。

# AGENTS.md

## 1. Role

You are Codex working inside the `model_library_mvp` repository.

Your role is to implement the engineering structure for a file-first cognitive model library MVP.

You are not responsible for product strategy, marketing, sales, UI design, or broad feature invention.

Product planning decisions come from the project owner and CCRA.

## 2. Project Goal

Build a minimal, file-first model library system that can represent cognitive models as:

- Human-readable Markdown model cards
- Machine-readable JSON model specs
- Source article records
- Source evidence excerpts
- Regression test cases
- Minimal model selector examples

The first sample models are:

- QPI
- Intellectual Archaeology

## 3. Core Principle

Do not overbuild.

The goal is not to create a full platform.  
The goal is to create a stable model asset foundation.

Prefer:

- JSON over database
- Markdown over UI
- Explicit schema over hidden convention
- Simple scripts over complex services
- Traceability over automation
- Validation over feature expansion

## 4. Non-Goals

Do not implement:

- Full frontend application
- Backend service
- Database
- Vector database
- Full RAG system
- User accounts
- Authentication
- Payment
- Public platform
- Multi-user collaboration
- Complete knowledge graph
- Automatic extraction from all articles
- Full question-answering system

If a task seems to require one of these, stop and ask for product confirmation.

## 5. Repository Layout

Expected layout:

```text
docs/
schemas/
models/
cards/
sources/
tests/
selector/
scripts/
reports/

Each folder should contain a README explaining its purpose.

6. Data Rules

Machine-readable files should use JSON.

Human-readable model cards and documentation should use Markdown.

Every model must have:

model_id
model_name
model_type
pipeline_position
one_sentence_definition
core_question
core_mechanism
source_articles
source_evidence
input_types
output_types
call_when
do_not_call_when
common_misuses
failure_modes
selection_priority
confidence_level
stability_profile
regression_status
productization_notes

7. Source Traceability Rules

Every model should reference source article IDs.

Every model should reference source evidence excerpt IDs.

Do not invent source IDs without adding matching records in sources/source_articles.json or sources/source_excerpts.json.

If source content is not yet available, use placeholder records with clear notes such as:

raw_excerpt: "待填入原文片段"

Do not pretend placeholder excerpts are verified evidence.

8. Regression Test Rules

Every core model should have at least five regression cases:

Positive cases
Boundary cases
Misuse cases

Regression tests should check whether the model is being used appropriately.

They are not unit tests for code only. They are also product tests for cognitive model stability.

9. Selector Rules

The minimal selector should not call an LLM in v0.1.

It should use simple matching rules:

Trigger keywords
Input types
Negative triggers
Pipeline position
Selection priority

The selector should output:

Recommended model IDs
Scores
Reasons
Routing notes

10. Coding Style

Keep scripts simple and readable.

Use Python only if scripts are needed.

Avoid unnecessary dependencies.

If using Python, prefer standard library first.

If a dependency is necessary, document it in README.

11. Validation Expectations

Validation should eventually check:

JSON schema compliance
Unique model IDs
Valid source article references
Valid evidence excerpt references
Valid regression test model references
Required fields
Enum values

Validation output should be written to:

reports/validation_report.md

12. Documentation Expectations

When adding or changing structure, update relevant documentation.

At minimum, keep these files consistent:

README.md
AGENTS.md
docs/PROJECT_BRIEF.md
docs/DATA_CONTRACT.md
docs/WORKFLOW.md
docs/DECISIONS.md

13. Decision Logging

Any structural decision should be recorded in:

docs/DECISIONS.md

Examples:

Why JSON is used instead of YAML
Why no database is used in v0.1
Why QPI and Intellectual Archaeology are the first sample models
Why selector is rule-based in v0.1

14. Definition of Done

A task is done only when:

Files are created in the expected location
README or folder README is updated
JSON files are valid or clearly marked as draft
References between files are consistent
Validation status is documented
Non-goals have not been violated
Any open questions are listed in the handoff document

15. Handoff Requirement

At the end of a work session, create or update:

docs/HANDOFF_TEMPLATE.md

or a concrete handoff file such as:

reports/Codex_工程产物摘要_v0.1.md

The handoff should include:

What was completed
What files changed
What assumptions were made
What does not yet work
What needs product judgment
Suggested next tasks


---

# 9. docs/PROJECT_BRIEF.md 应包含的内容

```markdown
# Project Brief

## 1. Product Context

This repository is the MVP foundation for a cognitive model management subsystem.

It supports a future problem-answering / cognitive-processing system that will use selected cognitive models to analyze user inputs.

## 2. First User

The first user is the project owner.

This is an OPC-oriented product workflow.  
The system should reduce the burden of managing, testing, and reusing cognitive models as a one-person company.

## 3. Core Need

The project solves a model asset management problem:

- Existing cognitive models are scattered across articles and previous model indexes.
- Model cards need stronger source traceability.
- Some early models require regression testing and stabilization.
- The future question-answering system needs callable model specifications.

## 4. MVP Focus

The MVP focuses on two models:

- QPI
- Intellectual Archaeology

These two models are used to validate the model extraction protocol.

## 5. Long-Term Direction

Future versions may support:

- 8-10 core models
- 20 extended models
- Model selector
- Multi-lens analysis workflow
- Conflict summarization
- Integrated question-answering system
- Source article integration
- Model regression dashboard

These are not part of v0.1 unless explicitly requested.

10. docs/DATA_CONTRACT.md 应包含的内容

# Data Contract

## 1. Machine-Readable Format

Use JSON for machine-readable data.

Main JSON objects:

- model card
- source article
- source excerpt
- regression case
- selector example

## 2. Human-Readable Format

Use Markdown for:

- model cards
- project documentation
- extraction notes
- validation reports
- handoff reports

## 3. Model Card Contract

Every model JSON should include:

- model_id
- model_name
- model_type
- pipeline_position
- one_sentence_definition
- core_question
- core_mechanism
- source_articles
- source_evidence
- input_types
- output_types
- call_when
- do_not_call_when
- common_misuses
- failure_modes
- selection_priority
- confidence_level
- stability_profile
- regression_status
- productization_notes

## 4. Source Article Contract

Every source article should include:

- source_id
- title
- source_type
- related_models
- source_status

Optional:

- author
- date
- file_path
- notes

## 5. Source Excerpt Contract

Every source excerpt should include:

- excerpt_id
- source_id
- related_model_id
- excerpt_type
- summary
- used_for

Optional:

- raw_excerpt
- confidence
- notes

## 6. Regression Case Contract

Every regression case should include:

- case_id
- model_id
- case_type
- input
- expected_behavior
- failure_signal

Optional:

- expected_output_elements
- notes

## 7. Reference Integrity

The following references must be valid:

- model.source_articles → sources/source_articles.json
- model.source_evidence → sources/source_excerpts.json
- regression_case.model_id → models/*.model.json
- source_excerpt.source_id → source_articles.json
- source_excerpt.related_model_id → models/*.model.json

11. docs/WORKFLOW.md 应包含的内容

# Workflow

## 1. Model Extraction Workflow

The project follows this flow:

```text
Original article / representative text
→ source article record
→ source evidence excerpts
→ human-readable model card
→ machine-readable model JSON
→ regression cases
→ selector examples
→ validation report

2. Development Workflow

For each task:

Read README.md and AGENTS.md.
Check docs/PROJECT_BRIEF.md.
Modify the smallest necessary set of files.
Keep JSON and Markdown versions consistent.
Run or update validation.
Update reports or handoff notes.
Do not expand scope without confirmation.

3. Model Addition Workflow

When adding a new model:

Create a model JSON file in models/.
Create a human-readable card in cards/.
Add source article records.
Add source evidence excerpts.
Add regression cases.
Add selector examples if relevant.
Run validation.
Update documentation.

4. Stabilization Workflow

If a model is unstable:

Mark needs_stabilization: true.
Add risks in stability_profile.main_risks.
Add boundary and misuse regression cases.
Do not upgrade to stability level A until tests pass.


---

# 12. docs/DECISIONS.md 应包含的内容

```markdown
# Decision Log

## Decision 001: File-first architecture

Status: Accepted

Reason:

The MVP should remain simple, local, transparent, and easy to inspect.  
A database is unnecessary before the model card schema and extraction protocol are stable.

## Decision 002: JSON for machine-readable model data

Status: Accepted

Reason:

JSON is easy to validate with JSON Schema and suitable for later integration into scripts, selectors, or applications.

## Decision 003: Markdown for human-readable model cards

Status: Accepted

Reason:

Markdown is easier for the project owner to read, edit, and review.

## Decision 004: QPI and Intellectual Archaeology as first sample models

Status: Accepted

Reason:

QPI represents a routing model.  
Intellectual Archaeology represents a deep modeling model.  
Together they test two different kinds of model structures.

## Decision 005: Rule-based selector in v0.1

Status: Accepted

Reason:

The first selector should validate data structure and model routing logic without relying on LLM calls.

13. docs/NON_GOALS.md 应包含的内容

# Non-Goals

The following are explicitly out of scope for v0.1:

## 1. Platform Features

- User accounts
- Authentication
- Authorization
- Payment
- Public website
- Admin dashboard
- Multi-user collaboration

## 2. Knowledge Infrastructure

- Full knowledge graph
- Vector database
- Large-scale RAG
- Automatic article ingestion
- Automatic model extraction from all articles

## 3. AI Workflow

- Full multi-agent pipeline
- LLM-based model selector
- Complete question-answering system
- Automated red-team review
- Automated model stabilization

## 4. Content Scope

- Managing all 100+ models
- Importing all historical articles
- Generating marketing content
- Generating sales copy

## 5. UI Scope

- Complex frontend
- Visual graph editor
- Drag-and-drop model editor
- Dashboard analytics

14. docs/HANDOFF_TEMPLATE.md 应包含的内容

# Codex Handoff Template

## 1. Current Work Session

Date:

Task:

## 2. Completed Work

- 

## 3. Files Created

- 

## 4. Files Modified

- 

## 5. Validation Status

- 

## 6. Assumptions Made

- 

## 7. Deviations From Plan

- 

## 8. Known Issues

- 

## 9. Questions for Product / CCRA

- 

## 10. Suggested Next Tasks

1. 
2. 
3.

15. 初始化时可以给 Codex 的完整指令

你可以把下面这段直接复制给 Codex：

请初始化当前项目为 `model_library_mvp`。

这是一个 file-first 的认知模型库 / 模型管理子系统 MVP。当前目标不是开发完整应用，而是为后续问题回答系统建立一个可维护、可追溯、可调用、可测试的模型资产底座。

请先完成项目初始化文档和目录结构，不要进入复杂编码。

请创建或更新：

- README.md
- AGENTS.md
- docs/PROJECT_BRIEF.md
- docs/DATA_CONTRACT.md
- docs/WORKFLOW.md
- docs/DECISIONS.md
- docs/NON_GOALS.md
- docs/HANDOFF_TEMPLATE.md

并创建以下目录及 README 占位说明：

- schemas/
- models/
- cards/
- sources/
- tests/
- selector/
- scripts/
- reports/

项目第一阶段只验证两个样板模型：

- QPI
- 思想考古 / Intellectual Archaeology

请在 README.md 和 AGENTS.md 中明确：

1. 本项目是 file-first 模型库 MVP；
2. 当前不做前端、不做数据库、不做 RAG、不做用户系统、不做完整问题回答系统；
3. JSON 用于机器可读数据；
4. Markdown 用于人读模型卡和项目文档；
5. 后续模型必须满足来源可追溯、结构可校验、边界可检查、误用可测试；
6. 每次修改结构性内容时，必须更新相关文档；
7. 每次阶段结束时，需要输出 handoff 文档，说明完成内容、文件变化、校验状态、问题和下一步建议。

请保持工程简单，不要过度设计。第一步只做项目初始化和规则文档。

16. 初始化完成后的验收标准

Codex 完成初始化后，你检查这些即可：

1. 根目录存在 README.md
2. 根目录存在 AGENTS.md
3. docs/ 下存在 6 个规则文档
4. schemas/ models/ cards/ sources/ tests/ selector/ scripts/ reports/ 目录存在
5. 每个目录有 README 或用途说明
6. README 清楚说明项目是什么和不是什么
7. AGENTS.md 清楚约束 Codex 不要过度开发
8. NON_GOALS.md 明确列出不做事项
9. DATA_CONTRACT.md 明确 JSON / Markdown 的分工
10. HANDOFF_TEMPLATE.md 能用于下一轮回到 ChatGPT / CCRA

这一步完成后，再让 Codex 进入下一阶段：创建 schema 和两个样板模型文件。

22 KiB Raw Blame History Unescape Escape