experienceos 0.7.2__tar.gz

experienceos-0.7.2/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# ExperienceOS runtime data (never commit a personal knowledge base)
+.experienceos/
+.experienceos-demo/
+
+# ZCode session-local tool state
+.zcode/
+
+
+# screenshot/demo scratch home
+.experienceos-shots/

experienceos-0.7.2/CHANGELOG.md

@@ -0,0 +1,273 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.7.2] - 2026-09-12
+
+First PyPI-distributed release: `pip install experienceos` now works,
+via the tag-driven trusted-publishing pipeline.
+
+### Changed
+
+- README quickstart installs from PyPI (`pip install experienceos`);
+  a PyPI version badge joins the badge row.
+
+### Fixed
+
+- Eval dataset manifest pins the LF digest: the sha256 was computed
+  over CRLF working-tree bytes, which never matches the `eol=lf`
+  checkouts every CI platform uses.
+- Codecov upload works: the coverage job now grants the
+  `id-token: write` permission the OIDC tokenless upload needs.
+
+## [0.7.1] - 2026-09-12
+
+Durability, index resilience and AI-prompt governance: closing the gap
+between "atomic" as an aspiration and as a verifiable property.
+
+### Added
+
+- Durable atomic writes: records, workflow checkpoints and shareable
+  reports are fsynced before `os.replace`, and the rename itself is
+  persisted on POSIX — a crash can no longer truncate *or* lose a write.
+- Cross-process write locking: the CLI, REST API and workbench may run
+  side by side; every store mutation holds an exclusive lock file lock
+  (Windows `msvcrt` / POSIX `flock`) so two writers cannot silently drop
+  each other's updates. Readers stay lock-free.
+- FTS resilience: index connections set a busy timeout instead of
+  failing instantly on a concurrent writer, and the query path detects
+  a silently stale index (row count drifted from the record files) and
+  rebuilds it from the source of truth.
+- Prompt governance: the evidence-brief system prompt is registered
+  with a version like every other template; checkpoints and sanitized
+  run reports record `prompt_versions`, and evaluation reports carry
+  them for attribution (`report_version` 3).
+- Schema-repair round: a final answer failing local schema validation
+  goes back to the model exactly once with the validation error before
+  the workflow pauses; a second invalid answer still pauses.
+- Governance files: SECURITY.md (threat model + disclosure policy) and
+  a Contributor Covenant CODE_OF_CONDUCT.md; CI uploads coverage to
+  Codecov.
+
+### Fixed
+
+- README's hardcoded test-count badge showed a stale number (the CI
+  badge is authoritative); CHANGELOG compare links pointed at a
+  non-existent organization and version tags were incomplete.
+- Packaging classifiers claimed Python 3.11 support, which the CI
+  matrix never tested.
+
+## [0.7.0] - 2026-09-11
+
+Workbench milestone (M6): the evidence-brief workflow, its evaluation
+harness, and a zero-dependency local browser workbench — plus network
+verification of evidence claims and a print-ready HTML export.
+
+### Added
+
+- Evidence-brief workflow (#032): a checkpointed model/tool loop — the model
+  must *read* records through three read-only tools before making claims;
+  citations are validated against evidence loaded during the run; every
+  round persists an atomic checkpoint so a paused run resumes exactly where
+  it stopped. Provider-neutral (OpenAI-compatible chat and the Responses API
+  ship with the box), with sanitized run reports (operational metrics only,
+  never prompts) and request metrics with optional per-model cost rates.
+- Evaluation harness (#032): `experienceos ai eval` replays a 9-case
+  labelled dataset (tool-sequence, schema-validity, citation-grounding and
+  expected-content assertions over deterministic recorded turns), writes
+  redacted shareable reports, and supports `--live` for real-model runs on
+  the same cases. Dataset ships with a signed-sha256 manifest that states
+  what the numbers are *not* valid for.
+- Local workbench (#033): `experienceos web` serves a zero-dependency
+  loopback-only browser UI for browsing experiences, running the brief
+  workflow (offline demo mode with synthetic data, or a configured live
+  model), inspecting tool-call timelines, and resuming paused runs.
+  Hardened by default: Host/Origin/Sec-Fetch-Site checks, strict CSP,
+  no request logging, errors kept off the wire.
+- Workbench run-history dropdown (#034): replaced the bare `<select>` with
+  a custom listbox showing each run's question, status dot (running/
+  paused/completed), mode and relative time; keyboard-navigable with
+  outside-click/Escape dismissal.
+- Evidence verification: `experienceos verify [id-prefix]` checks GitHub-
+  backed evidence against the REST API — repositories, commits (with
+  author/date) and pull requests (author/state/merged). Non-GitHub URLs
+  get an existence probe; local paths are skipped. `--json` writes a
+  machine-readable report; exit code 1 on anything missing, so it can
+  gate CI like `lint`.
+- HTML exporter: `experienceos export html` renders a self-contained,
+  print-ready profile page (inline stylesheet, evidence links, escaped
+  verbatim content) — "Print → PDF" with no extra tooling.
+- Release engineering: tag-driven workflow builds sdist+wheel, smoke-tests
+  the wheel outside the repository, creates the GitHub Release, and
+  publishes to PyPI via trusted publishing when `PYPI_PUBLISH=true`.
+
+### Changed
+
+- `AIProviderError` now carries sanitized request `metadata`; the AI
+  config gained explicit retry-budget and cost-rate fields
+  (`ai.timeout_seconds` replaces `ai.timeout`). The layering guard now
+  allows ai's read-only tool seam to import storage (downward, acyclic).
+
+## [0.6.0] - 2026-08-30
+
+Architecture-hardening release: a full-codebase review whose findings were
+fixed structurally (no special-case patches). Details in
+`docs/issues/m5-hardening.md`.
+
+### Added
+
+- Project-files connector (#027): `experienceos import /path/to/folder`
+  turns a non-git project directory into one honest draft — title from the
+  folder name, description verbatim from the README, languages from the
+  shared extension map, explicit undated period, empty contributions.
+  Walk safety: junk/build dirs pruned, directory symlinks never followed,
+  file-count cap.
+- Shared language module `connectors/languages.py` (#027): one curated
+  extension→language map now serves both git-repo and project-files.
+- Injection protocols (#028): `MaterialDraftExtractor` /
+  `AcceptsMaterialExtractor` in `connectors.base`; the AI extraction
+  pipeline (`ai.extraction.AIExtraction`) is wired by the composition
+  root, so any connector can use AI reading without importing the ai tier.
+- Layering guard tests (#028): `tests/test_layering.py` parses every
+  module's imports (AST) and fails when a tier reaches where it must not.
+- Interview confirmation now includes `evidence` (#030): AI-harvested
+  evidence candidates pass the same keep/drop gate as every other field.
+
+### Changed
+
+- **Breaking (internal API)**: `ExperienceDraft` moved to
+  `core.draft` (re-exported from `connectors.base`); the material→draft
+  pipeline moved from `ai.interview` to `ai.extraction` (names re-exported);
+  `ResumeExtractor(provider=..., model=...)` replaced by
+  `ResumeExtractor(material_extractor)` / `set_material_extractor()`.
+- Unified query path (#029): `services.query_results` is the single
+  entry point for CLI and API; the FTS index only pre-filters candidates
+  while the in-memory engine always does final filtering and scoring —
+  scores and ranking are now identical with and without an index (the
+  FTS path previously discarded both).
+- `SourceOrigin` gained `project_files`; `UNDATED_START` is defined once
+  in `core.models`; GitHub User-Agent reports the package version.
+
+### Fixed
+
+- Stale `import --help` text still claiming PDF resumes were not supported.
+
+## [0.5.0] - 2026-08-29
+
+### Added
+
+- Service layer + FastAPI (#018): `services/` holds the use cases (CLI and
+  API are thin shells); optional `[api]` extra serves read endpoints
+  (/experiences, /search, /stats, /lint) plus draft-only creation via
+  `experienceos-serve`.
+- Plugin system (#019): built-ins declared as entry points; third-party
+  packages register connectors/exporters by declaring their own;
+  `experienceos plugins list` shows source, version and load state.
+- Schema migrations (#020): ordered version steps, transparent read-path
+  migration with backup under `<home>/backup/`, `migrate --check`.
+- Sync & backup (#021): `experienceos sync [--init|--push REMOTE]` commits
+  the home with git; `experienceos backup` writes a restore-ready zip.
+- FTS index (#022): rebuildable SQLite FTS5 index (CJK unigram split);
+  text queries use it only above the record threshold; files stay the
+  source of truth. Benchmark script included.
+
+## [0.4.0] - 2026-08-29
+
+Output milestone (M3): faithful projections of confirmed records.
+
+### Added
+
+- Exporter framework (#014): `Exporter` protocol, name-keyed registry and the
+  `experienceos export <name>` command with SearchQuery-backed filters;
+  defaults to active records so drafts never leak into artifacts.
+- Markdown exporter (#015): time-sorted profile with STAR structure and
+  evidence lists, plus an `--timeline` by-year view; stdlib
+  `string.Template` keeps it dependency-free; golden-file tests pin output.
+- JSON Resume exporter (#016): jsonresume.org-compatible mapping
+  (work/projects, technology -> keywords, url evidence -> url) validated by
+  strict pydantic models; unexportable fields are dropped and itemized on
+  stderr instead of being rewritten.
+- Skill profile (#017): `experienceos profile` (technology timeline,
+  co-occurrence Top-N, per-year evidence coverage) and machine-readable
+  `stats --json`, backed by a shared pure-function stats module.
+
+## [0.3.0] - 2026-08-29
+
+Intelligence milestone (M2): provider wiring and AI-assisted drafting.
+
+### Added
+
+- LLM provider wiring (#010): `OpenAICompatibleProvider` completes the M0 skeleton — configurable timeout (`ai.timeout`), exactly one retry for network-class errors, and 429/5xx responses surfaced as `AIProviderError` with a response-body summary. New `experienceos config get/set/list` subcommands edit config.toml (secrets stay in env vars), `experienceos ai check` verifies the endpoint end to end (`--mock` targets the scripted provider), and `MockProvider` moves into the core `ai` package for tests and `--dry-run` modes.
+
+## [0.2.0] - 2026-08-29
+
+Import milestone (M1): every connector produces drafts only, with provenance.
+
+### Added
+
+- Resume importer (#009): rule-based (no LLM) parsing of Markdown/plain-text
+  resumes into experience drafts — common CN/EN section headings, entry
+  splitting on headings/bold/date lines, `YYYY-MM` period parsing (incl.
+  `至今/present`, year-only ranges), curated technology keywords plus inline
+  code spans, verbatim descriptions, and the source file attached as `file`
+  evidence with `source.ref`. Undated entries carry an explicit `1970-01`
+  placeholder tagged `undated`; PDF input is rejected until the M2 AI
+  extraction path (#012).
+- Local git repository analyzer (#008): read-only `git log` analysis of a
+  local checkout — activity window, author-attributed commit count and
+  median change size, extension-based language composition (built-in map,
+  no linguist), repo-path evidence plus the GitHub URL when an `origin`
+  remote points at github.com. `--author` defaults to the repository's
+  `git config user.email`; non-git directories, submodules and shallow
+  clones fail or degrade with readable errors.
+- GitHub importer (#007): authenticated-user or explicit-author activity
+  import, repository languages, paginated commits/PRs/issues, evidence-backed
+  drafts, actionable authentication/rate-limit errors, and offline API fixtures.
+- Connector framework (#006): `Extractor` protocol, `ExperienceDraft`
+  (forced `status=draft` + mandatory provenance), `scheme:payload` source
+  routing with Windows-drive-letter safety, name-keyed registry, and the
+  `experienceos import` command (preview confirmation, never overwrites
+  existing records).
+
+### Fixed
+
+- Experience detail rendering now uses ASCII-safe list/evidence markers and
+  folds long evidence URLs correctly on Windows GBK consoles.
+
+## [0.1.0] - 2026-08-25
+
+First public foundation release (Milestone 0).
+
+### Added
+
+- Core `Experience` domain model (pydantic v2) with strict validation,
+  schema versioning, evidence and provenance (`source`) sub-models.
+- Time-sortable ULID identifier generation (stdlib only).
+- Local-first file storage layer: one JSON file per experience, atomic
+  writes, corruption-tolerant listing, `validate` reporting.
+- In-memory search engine: weighted full-text matching plus filters by
+  type / tag / technology / status / period overlap.
+- CLI (`experienceos`): `init`, `add`, `list`, `show`, `search`, `set`,
+  `add-item`, `edit`, `delete`, `stats`, `validate`, `path`.
+- AI layer scaffolding: `LLMProvider` protocol, OpenAI-compatible provider
+  skeleton (optional `[ai]` extra), versioned prompt templates.
+- Project docs: README (zh-CN), ARCHITECTURE, ROADMAP, CONTRIBUTING and a
+  GitHub-ready issue backlog split by milestone.
+- CI workflow (GitHub Actions: ruff + pytest on Python 3.10-3.13,
+  Ubuntu + Windows).
+
+[Unreleased]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.7.2...HEAD
+[0.7.2]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.7.1...v0.7.2
+[0.7.1]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/guomengjia618-dot/ExperienceOS/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/guomengjia618-dot/ExperienceOS/releases/tag/v0.1.0

experienceos-0.7.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExperienceOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

experienceos-0.7.2/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.5
+Name: experienceos
+Version: 0.7.2
+Summary: ExperienceOS - an open-source personal experience operating system. Never forget what you have built.
+Project-URL: Homepage, https://github.com/guomengjia618-dot/ExperienceOS
+Project-URL: Documentation, https://github.com/guomengjia618-dot/ExperienceOS/tree/main/docs
+Author: ExperienceOS Contributors
+License: MIT License
+        
+        Copyright (c) 2026 ExperienceOS Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agent,career,experience,knowledge-base,personal-os
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: ai
+Requires-Dist: httpx>=0.27; extra == 'ai'
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100; extra == 'api'
+Requires-Dist: uvicorn>=0.30; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: github
+Requires-Dist: httpx>=0.27; extra == 'github'
+Provides-Extra: pdf
+Requires-Dist: pypdf>=4.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# ExperienceOS
+
+[English](README.en.md) | 简体中文
+
+[![CI](https://github.com/guomengjia618-dot/ExperienceOS/actions/workflows/ci.yml/badge.svg)](https://github.com/guomengjia618-dot/ExperienceOS/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/guomengjia618-dot/ExperienceOS/graph/badge.svg)](https://codecov.io/gh/guomengjia618-dot/ExperienceOS)
+[![PyPI](https://img.shields.io/pypi/v/experienceos)](https://pypi.org/project/experienceos/)
+![Python](https://img.shields.io/badge/python-3.10%20%7C%203.12%20%7C%203.13-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![Coverage](https://img.shields.io/badge/tests-448%20passed-brightgreen)](#工程质量)
+
+> **Never forget what you have built.** 把你做过的每一件事，变成有证据支撑的经历资产。
+>
+> **English abstract** — ExperienceOS is an open-source personal experience
+> operating system for developers. It turns fragmented traces of what you
+> have built (code, repositories, GitHub activity, resumes, conversations)
+> into structured, evidence-backed *Experience Assets* that live on your
+> machine, under your control. It is **not** a resume generator.
+
+ExperienceOS 是一个开源的 **AI 个人经历操作系统**（Personal Experience
+Operating System）。它帮助开发者记录、整理、理解和沉淀自己参与过的所有
+项目与创造经历，建立长期的个人经历知识库。
+
+很多开发者都有类似的困境：做过大量项目，几年后却想不起细节；GitHub
+仓库一堆，却没有结构化的整理；到了面试或跳槽才临时抱佛脚。项目的真实
+价值散落在代码、commit、文档和个人记忆的碎片里。
+
+ExperienceOS 要做的事情只有一件：**把这些碎片转化为有证据支撑的结构化
+经历资产（Experience Asset）**。
+
+![ExperienceOS 本地工作台](docs/assets/workbench-brief.png)
+
+## 核心理念
+
+1. **发现、整理、保存真实经历** —— 而不是创造经历。ExperienceOS 不是
+   简历生成器，不做包装，不夸大事实。
+2. **能力描述尽可能关联证据**。每条 contribution / result 都可以挂上
+   repo、commit、PR、文档等 Evidence。
+3. **AI 只辅助表达，不代替事实**。AI 产出永远是「提案」，经用户确认才
+   入库，并且 `source.created_by` 会如实记录内容来自用户还是 `ai:<model>`。
+4. **本地优先（Local-first）**。你的经历库是纯 JSON 文件，存放在
+   `~/.experienceos/`，人可读、可 git 版本化、永远属于你。
+
+## 5 分钟上手
+
+### 0) 先看效果：离线工作台（无需任何配置）
+
+```bash
+pip install experienceos        # 或从源码安装:pip install -e .
+experienceos web                # 浏览器打开 http://127.0.0.1:8765
+```
+
+工作台自带 **离线演示模式**：3 条合成示例经历 + 确定性回放模型，完整演示
+AI 取证流程——检索经历 → 逐条读取 → 证据统计 → 生成带引用的证据简报，
+还可以模拟「模型中断」并从检查点恢复。全程不联网、不访问你的真实数据。
+
+### 1) 录入真实经历
+
+```bash
+experienceos init          # 初始化 ~/.experienceos
+experienceos add           # 交互式录入第一条经历
+experienceos import .      # 或直接把当前项目导入为草稿（见下文）
+experienceos list          # 浏览全部经历
+experienceos search "搜索引擎 inverted index"
+```
+
+### 2) 接上真实模型（可选）
+
+```bash
+experienceos config set ai.model glm-4.7      # GLM / DeepSeek / OpenAI / Ollama 均可
+experienceos ai check                          # 结构化输出连通性自检
+experienceos ai eval --live                    # 用真实模型跑同一套评测集
+```
+
+## 导入：把碎片变成草稿
+
+所有导入器只产 `status=draft` 草稿，预览确认后才入库；`source` 字段
+如实记录来源。
+
+| 来源 | 命令 | 说明 |
+| --- | --- | --- |
+| GitHub | `experienceos import github:owner/repo --author username` | 公开仓库无需 token；私有活动用 `GITHUB_TOKEN`（只读环境变量） |
+| 本地 Git 仓库 | `experienceos import /path/to/repo` | 只读 `git log` 分析：时间窗、语言构成、贡献摘要 |
+| 普通文件夹 | `experienceos import /path/to/folder` | 无版本控制的项目包；没有可信时间线就诚实留白 |
+| 旧简历 | `experienceos import resume:cv.md` | 纯规则解析（不用 LLM），原句不改写，原文挂为证据 |
+
+## AI 证据简报工作流
+
+`experienceos ai brief "…"` 是这个项目的核心创新：**模型不允许凭空作答**。
+
+- 模型必须先通过三个只读工具检查本地档案——`search_experiences` →
+  `get_experience` → `get_evidence_stats`；
+- 简报中的每一条**引用必须对应本次运行中实际读取到的证据位置**，
+  引用不接地（grounding failure）会被判暂停而不是输出幻觉；
+- 每一轮对话都持久化为**原子检查点**（fsync 背书），checkpoint 记录
+  prompt 版本，模型中断/网络失败后从保存的进度精确恢复；最终输出
+  schema 不合法时先做**一轮修复重试**，仍不合法才判暂停；
+- 运行报告默认**脱敏**：只有延迟、token、重试、prompt 版本等运营指标，
+  绝无 prompt 内容与个人数据。
+
+**可检验的 AI 质量**——不靠感觉，靠评测集：
+
+```bash
+$ experienceos ai eval
+Evaluation (recorded): 9/9 expectations passed (100%)
+tool sequence 100% · schema 100% · grounding 100% · completion 100% · recovery 100%
+```
+
+9 条带标签的评测用例断言工具调用序列、schema 合法性、引用接地和错误恢复；
+`--live` 可用真实模型跑同一数据集。数据集附 sha256 manifest，并明确声明
+这些数字**不**可用于模型准确率宣传。诚实边界：接地校验是**存在性校验**
+（引用的证据确实在本次运行中被读取过），不等于语义蕴含——它保证结论的
+出处可回溯，不能替代人对结论的判断。
+
+**证据可以自动核验**——`experienceos verify` 把每条 GitHub 证据拿去
+REST API 对证：仓库、commit（含作者与日期）、PR（作者/状态/是否合并），
+非 GitHub 链接做存在性探测，本地路径如实跳过；发现失效证据以退出码 1
+报告，可接入 CI。
+
+![工作台的运行记录时间线：检索 → 逐条读取 → 证据统计 → 校验通过](docs/assets/workbench-timeline.png)
+
+## 平台与导出
+
+```bash
+experienceos sync --init      # home 目录 git 化（--push origin 推送，注意私有仓库）
+experienceos backup           # 全量打包成 zip（含 config）
+experienceos index rebuild    # 可选 FTS 索引（大库加速，可随时删除重建）
+experienceos plugins list     # entry-points 插件（第三方 connector/exporter）
+pip install 'experienceos[api]' && experienceos-serve   # 本地 REST API（只读）
+```
+
+导出物永远是经历的忠实投影，默认只导出 `active` 记录（draft 不外泄）：
+
+```bash
+experienceos export markdown                    # 个人档案（STAR + evidence）
+experienceos export markdown --timeline         # 按年分组的简表
+experienceos export html                        # 自包含网页档案（打印即 PDF）
+experienceos export json-resume                 # jsonresume.org 兼容格式
+experienceos profile                            # 技能时间线 / 共现 Top-N / 覆盖趋势
+experienceos stats --json                       # 机器可读统计
+experienceos verify                             # 联网核验 GitHub 证据（可接 CI）
+```
+
+## 架构
+
+```mermaid
+flowchart TB
+    subgraph composition["组合根（不受分层限制）"]
+        CLI["cli (typer)"]
+        API["api (FastAPI, 只读)"]
+        WEB["web (stdlib http.server, loopback)"]
+    end
+    subgraph intelligence["ai 层"]
+        WF["evidence-brief workflow<br/>检查点 + 引用接地校验"]
+        TOOLS["只读工具注册表"]
+        EVAL["评测集 + 回放 harness"]
+        PROVIDER["provider 协议<br/>openai-compat / responses"]
+    end
+    SERVICES["services 用例层"]
+    subgraph data["数据层"]
+        CONN["connectors<br/>github / git / folder / resume"]
+        EXP["exporters<br/>markdown / json-resume"]
+        STORE["storage<br/>JSON source of truth + FTS5 索引"]
+    end
+    CORE["core 领域模型<br/>Experience / Evidence / ULID / 错误体系"]
+
+    CLI --> SERVICES
+    API --> SERVICES
+    WEB --> WF
+    WF --> TOOLS --> STORE
+    WF --> PROVIDER
+    EVAL --> WF
+    SERVICES --> CONN
+    SERVICES --> EXP
+    SERVICES --> STORE
+    CONN --> CORE
+    EXP --> CORE
+    STORE --> CORE
+```
+
+分层由 **AST 守卫测试**强制执行（`tests/test_layering.py`）：core 不依赖
+任何上层；ai 永远不碰 connectors；services 编排一切；cli/api/web 是组合根。
+
+## Experience 数据模型
+
+每个经历是一个统一的 `Experience` 抽象——不只是代码项目，还包括毕业设计、
+课程实践、竞赛、实习、开源贡献、个人作品和研究项目。
+
+```json
+{
+  "id": "exp_01J...",
+  "schema_version": 1,
+  "title": "Campus Search Engine",
+  "type": "course_project",
+  "period": { "start": "2023-01", "end": "2023-06" },
+  "context": "数据库课程大作业，三人小组",
+  "role": "检索引擎负责人",
+  "description": "为校园文档构建的轻量搜索引擎",
+  "technology": ["Python", "Whoosh"],
+  "contribution": ["设计倒排索引与查询流水线"],
+  "challenge": ["中文分词在长文档上召回率低"],
+  "solution": ["引入 jieba 自定义词典 + 混合 BM25 排序"],
+  "result": ["课程演示中 top-10 命中率 92%"],
+  "reflection": "第一次体会到评测集对检索系统的重要性。",
+  "evidence": [
+    { "kind": "repo", "location": "github.com/you/campus-search" }
+  ],
+  "tags": ["ir", "backend"],
+  "status": "active",
+  "source": { "origin": "manual", "created_by": "user" }
+}
+```
+
+完整字段说明见 `docs/ARCHITECTURE.md`。
+
+## 工程质量
+
+- **448 个测试全绿（覆盖率约 90%）**：领域、存储（含 FTS 与迁移）、连接器、
+  AI 工作流与评测、web 服务端到端；
+- **崩溃安全与并发写保护**：所有落盘写入先 fsync 再原子替换，跨进程写入
+  由文件锁串行化（CLI / API / 工作台可并存），FTS 索引陈旧自动重建；
+- **CI 矩阵**：Ubuntu + Windows × Python 3.10/3.12/3.13，外加 wheel 打包
+  在仓库外安装验证（`ai eval` 从安装产物内运行），覆盖率上报 Codecov；
+- **AST 分层守卫**：依赖方向由测试而非约定保证；
+- **AI 评测集**：确定性回归 + 可选真模型评测，checkpoint 与报告记录
+  prompt 版本，报告默认脱敏。
+
+## 路线图
+
+| Milestone | 主题 | 版本 | 状态 |
+| --- | --- | --- | --- |
+| M0 | 基础：数据模型 + 本地存储 + CLI | 0.1.0 | ✅ |
+| M1 | 导入：GitHub / 本地仓库 / 简历 Connector | 0.2.0 | ✅ |
+| M2 | 智能：AI 面试录入、enrich 提案、证据护栏 | 0.3.0 | ✅ |
+| M3 | 输出：Markdown 档案 / JSON Resume 导出 | 0.4.0 | ✅ |
+| M4 | 平台：API 服务、插件系统、FTS 索引 | 0.5.0 | ✅ |
+| M5 | 加固：项目文件夹导入、分层守卫、查询语义统一 | 0.6.0 | ✅ |
+| M6 | 工作台：证据简报工作流、评测集、本地浏览器工作台 | 0.7.0 | ✅ |
+
+第一阶段的目标用户是开发者（应届程序员、软件工程师、AI 工程师、开源
+贡献者）；Experience 抽象刻意保持职业中立，未来可扩展到**设计师**、
+**研究人员**与**创作者**（扩展路径见 `docs/ROADMAP.md` 的「未来用户」）。
+
+详见 `docs/ROADMAP.md` 与 `docs/issues/`（GitHub-ready 的 Issue 拆分）。
+
+## 项目结构
+
+```
+src/experienceos/
+  core/        # 领域模型：Experience / Evidence / Source + ULID + 错误体系
+  storage/     # 文件存储层（原子写、损坏容忍、stat 缓存）+ 查询引擎 + FTS 索引
+  connectors/  # GitHub / 本地 Git / 项目文件夹 / 简历等导入器
+  ai/          # 证据简报工作流 + 只读工具 + 评测 harness + Provider + 版本化 Prompt
+  services/    # 用例层：CLI 与 API 复用的查询 / 导入 / 统计逻辑
+  exporters/   # Markdown / JSON Resume 导出
+  web/         # 本地浏览器工作台（零依赖 http.server + 静态前端）
+  api/         # FastAPI 只读 REST API
+  cli/         # typer 命令行界面
+  config.py    # home 目录与 config.toml
+evals/         # 9 条带标签的 AI 评测用例 + sha256 manifest
+examples/      # 可运行的离线 agent 演示脚本
+```
+
+## 参与贡献
+
+欢迎 Issue / PR。开发环境、提交规范与评审流程见
+[CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## License
+
+[MIT](LICENSE) © ExperienceOS Contributors