helen-lang 1.20.0__tar.gz

helen_lang-1.20.0/CLAUDE.md

@@ -0,0 +1,258 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working in the **Helen** repo.
+For the broader multi-project layout, see `../CLAUDE.md`.
+
+## Overview
+
+**Helen** — a prompt-first Agent programming language (AI-native DSL).
+Combines deterministic constructs (variables, functions, control flow) with
+first-class LLM primitives (`llm act`, `llm if`).
+
+## Development Commands
+
+```bash
+uv pip install -e .                 # Install in editable mode (Python 3.12+, using uv)
+uv pip install -e ".[dev]"          # Install dev dependencies (pytest, flake8)
+# 或者使用传统 pip
+pip install -e .                    # Install in editable mode (Python 3.12+)
+pip install -e ".[dev]"             # Install dev dependencies (pytest, flake8)
+
+# Running programs
+helen <file.helen>              # Execute a Helen program
+helen check <file.helen>        # Validate syntax/semantics without executing
+helen repl                      # Interactive REPL
+
+# Testing
+pytest                              # Run all 2791+ tests
+pytest tests/core/                  # Run tests for a specific module
+pytest tests/execution/test_functions.py::test_function_call -v  # Single test
+helen test <file.helen>             # Run Helen's built-in test framework
+helen test <file.helen> --only "name" --suite "suite"  # Filtered test run
+
+# Quality & tooling
+flake8 helen/                       # Lint (max-line-length=120, E501 ignored)
+helen quality <file.helen>          # 7-dimension quality assessment
+helen doc <file.helen>              # Generate documentation
+helen lsp                           # Start Language Server (JSON-RPC over stdio)
+helen init                          # Initialize ~/.helen/ config directory
+```
+
+## Architecture (3-layer pipeline)
+
+```
+Layer 1: Helen Core (pure language)
+  Lexer (maximal-munch, frozenset O(1) lookup, 89 bilingual keywords)
+    → Parser (Pratt precedence + recursive descent)
+    → AST (64 frozen dataclass nodes, Visitor pattern)
+    → SemanticAnalyzer (two-pass for forward refs, SymbolTable, 14-type system)
+    → Interpreter (environment chain, sentinels for control flow)
+
+Layer 2: Runtime (LLM integration)
+  LLMRuntime (abstract) → HttpLLMRuntime (httpx connection pool, OpenAI-compatible API)
+  Tools (10 built-in: web_search, web_fetch, read/write/patch_file, shell_exec, calculate, load_skill, find_files, search_files)
+  ImportResolver (.helen/.json/.yaml/.md/.txt/Python), Config, History (with compression)
+  TranscriptStore (v1.16: SSOT for all messages, SQLite/JSONL backends, LRU cache, UUID addressing)
+
+Layer 3: Toolchain
+  CLI (run/check/repl/test/quality/doc/init/lsp)
+  REPL (multi-line, :help/:reset/:ask/:agent/:trace/:stats/:llm_log/:last_error/:transcript/:sessions/:session_id)
+  LSP (diagnostics, completion, go-to-definition, alias-aware)
+  VS Code Extension (syntax highlighting + LSP)
+```
+
+## Key Source Layout
+
+```
+helen/
+├── core/          # lexer.py, parser.py, ast.py, tokens.py, errors.py, source_span.py
+├── semantic/      # analyzer.py (two-pass semantic analysis)
+├── interpreter/   # interpreter.py, llm_mixin.py (LLM visitor methods), environment.py, exceptions.py
+├── runtime/       # llm_runtime.py, http_llm.py, tools.py, config.py, import_resolver.py
+│                  # prompt_builder.py (system prompt + skill index), history.py, observability.py
+│                  # fuzzy_match.py (9-strategy file patching)
+│                  # transcript_store.py (v1.16: SSOT, SQLiteBackend, JSONLBackend, LRU cache)
+│                  # session_manager.py (v1.16: session lifecycle, path management)
+│                  # channel.py (v1.18: Channel + ChannelEndpoint message queue)
+├── stdlib/        # 287 built-in functions (string, math, crypto, collections, test, quality, context, transcript, media, etc.)
+│                  # locales/zh.py (287 Chinese aliases)
+│                  # mailbox.py (v1.18: mailbox_select for multi-channel select)
+├── ffi/           # Python FFI for importing Python modules from Helen
+├── cli/           # __main__.py (entry point), repl.py, formatter.py, docgen.py
+├── lsp/           # Language Server Protocol (JSON-RPC 2.0 over stdio)
+├── agent/         # Helen assistant program (helen_assistant.helen)
+└── skills/        # 16 built-in skills (SKILL.md + references/) — distributed with the package
+    ├── software-development/  # helen-syntax, helen-stdlib, helen-testing, helen-quality,
+    │                          # helen-agent-patterns, helen-agent-collaboration,
+    │                          # helen-language-development, helen-programming-methodology,
+    │                          # code-quality, debugging, plan, tdd, subagent-driven, writing-plans
+    └── devops/                # github, hellen-consistency-checker
+```
+
+## Language Concepts
+
+- **Agent declarations**: First-class `agent` blocks with description, model, temperature, tools, prompt template (`{{var}}`), `functions {}` block (becomes LLM-callable tools), and `main {}` logic
+- **Agent isolation levels (v1.12)**: Three decorator levels control scope access:
+  - `@open agent`: Can access and modify module-level `let` (breaks isolation)
+  - `@strict agent`: Deep-copies shared let on access (prevents accidental mutation)
+  - `@sandbox agent`: Forces `tools=[]` (no external tools, only load_skill)
+  - Default (no decorator): Standard isolation — module `let` invisible, `const` auto-visible read-only
+- **Shared store & channel (v1.12-v1.13)**: Thread-safe shared state containers
+  - `shared store Name { fields, methods }` — mutable shared state with RLock protection
+  - `通道` (channel) — Chinese alias for `shared store` (same declaration syntax, same runtime)
+  - Chinese keywords: `仓库` (store), `通道` (channel alias)
+  - `_` prefix fields are private (inaccessible from agent code)
+- **Channel message queue (v1.18)**: `spawn` returns a Channel (mailbox) for message-passing concurrency
+  - `spawn Agent(...)` — spawns agent, returns Channel immediately
+  - Channel methods: `send(msg)`, `receive()`, `try_receive()`, `cancel()`, `close()`
+  - `mailbox_select([m1, m2])` — multi-channel select (first-ready wins)
+  - Chinese aliases: `发送()`, `接收()`, `尝试接收()`, `取消()`, `关闭()`
+  - **Streaming interrupt (v1.18)**: `on_chunk` callback return `false` to stop streaming; Ctrl+C during streaming interrupts and preserves REPL state; `spawn` + `Channel.cancel()` can interrupt background agent streaming
+  - **Stdlib**: `cancel_llm_call()`, `current_llm_call_id()`, `cancel_all_llm_calls()`
+  - **中文别名**: `取消大模型调用`, `当前大模型调用id`, `取消所有大模型调用`
+- **ReadOnlyView (v1.12)**: Immutable wrapper for agent parameters
+  - Blocks all mutation attempts → raises `ScopeViolationError`
+  - Supports `__getitem__`, `__len__`, `__iter__`, `__contains__`, `__bool__`, `__str__`, comparison operators, `__add__`, `__radd__`, `__hash__`
+  - Nested iterables auto-wrapped on iteration
+  - dict methods: `keys()`, `values()`, `items()`, `get()`
+- **Agent scope isolation (v1.10)**: `agent main {}` runs in isolated environment. Module-level `let` is **not** visible inside agent main (compile-time error). Module-level `const` is auto-visible (read-only sharing). Use `shared let` for cross-agent visible mutable variables. Closures in agent main can capture local variables.
+- **Closure value capture**: Closures capture a **deep copy** of reference-type variables (snapshot semantics, immune to subsequent modifications)
+- **LLM primitives**: `llm act` (tool-calling loop + optional callbacks, usable as expression since v1.10), `llm if` (LLM-routed branching)
+  - v1.14: `llm stream` **deleted** — streaming merged into `llm act` with optional callbacks
+  - v1.17: 新增 `on_media` / `on_generate` / `provider` 子句，支持多模态输入与文生图/视频
+  - Syntax: `llm act "prompt" [media(...)] [provider("...")] [on_media fn(...)] [on_generate fn(...)] [on_chunk fn(...)] [on_complete fn(...)]`
+- **Multimodal support (v1.17)**: 回调即适配器——协议差异由用户回调处理，Helen 核心不内置 provider 格式
+  - **`media()` stdlib 函数**：普通函数（非关键字），返回 `MediaPart` 对象，自动识别文件路径/URL/base64
+  - **`MediaPart` 数据类型**：一等公民，可赋值、传参、存入列表；字段：`source`/`content`/`mime`/`media_type`/`metadata`
+  - **`on_media fn(parts, provider)`**：多模态输入适配器，将 `MediaPart` 列表转换为 provider 特定格式（Content Parts）；不指定时使用默认 OpenAI 兼容适配器
+  - **`on_generate fn(params)`**：将生成能力注册为工具，LLM 在工具循环中决定是否调用；支持文生图、文生视频等，协议差异完全由回调处理
+  - **设计原则**：协议未统一时不固化进语法；未来新模态/新协议无需修改语言核心，用户更新回调或 skill 即可
+  - **配套 skill**：`multimodal-providers` 提供各主流 provider（OpenAI/Claude/Gemini/Seedance/Kling 等）的标准回调写法模板
+  - **中文别名**：`媒体()`, `媒体base64()`, `是媒体()`, `媒体类型()`, `处理媒体 fn(...)`, `生成 fn(...)`
+- **spawn + Channel (v1.18)**: `spawn Agent(...)` spawns an agent and returns a Channel (mailbox) immediately. The spawned agent runs in an isolated environment with a deep-copied snapshot of ALL variables (including SharedStore). Inter-agent data sharing is done explicitly by passing SharedStore references through Channel messages. `mailbox_select([m1, m2, ...])` provides multi-channel select (first-ready wins). Old async/await/detach keywords and `channel X { fields }` declaration syntax removed (v1.18).
+- **Short-circuit evaluation (v1.10)**: `&&` and `||` short-circuit
+- **Type system**: 14 types including Optional (`str?`), Union (`int | str`), Protocol, Agent, Literal. Return type annotation uses `:` syntax only (`fn foo(): int {}`); `->` syntax removed (v1.10)
+- **Pattern matching**: `match` with range, wildcard, variable binding, type patterns
+- **Exception hierarchy**: `AnyError → LLMError → TimeoutError/ModelError/AgentError`, `ToolError`, `RuntimeError` (including wrapped stdlib Python exceptions since v1.10), `AssertionError`, `AggregateError`, `ScopeViolationError`
+- **Imports**: Multi-format (`.helen`, `.json`, `.yaml`, `.md`, `.txt`, Python), circular detection; imported `shared let` tracked correctly since v1.10
+- **Chinese support**: 89 bilingual keywords (44.5 English + 44.5 Chinese) with full bilingual support (CJK identifiers, fullwidth punctuation since v1.10, Chinese quotes since v1.10)
+- **Subscript/field assignment (v1.10)**: `arr[i] = x` and `obj.field = x` are supported as assignment targets
+- **Alias statement (v1.10)**: `alias <canonical> as <alias_name>` / `别名 <canonical> 为 <alias_name>` — create aliases for stdlib, user functions, agents, and variables
+- **Context management (v1.12, v1.19)**: `clear_context()` clears conversation history; `compress_context(strategy)` with strategies: `auto`, `summarize`, `truncate`, `none`. v1.19 adds 24 new stdlib functions covering 6 dimensions: Inspection (`context_stats`, `context_usage`), Working Memory (`working_memory_get/set/remove/clear`), Fine-grained Mutation (`insert/replace/delete/pin/unpin_message`), Runtime Config (`set_compression_strategy/set_context_window/set_working_memory_enabled/set_cache_aware/get_context_config`), Query (`search_context/context_slice`), Multi-Agent Transfer (`export/import/fork_context`), Lifecycle Hooks (`on_compression/on_context_overflow`). Pinned messages are immune to all 5 graduated compression layers. `classify_message` internalized (no longer public).
+- **Context enhancement (v1.15, Phase 1-7)**:
+  - **Working Memory**: Automatically tracks active files, recent decisions, pending TODOs, error history
+  - **Graduated Compression**: Five-layer progressive compression (Layer 1-5, from 60% to 95% usage)
+  - **Cache-Aware Compression**: Preserves stable prefix (30%), improves cache hit rate from 10-20% to 70-80%
+  - **Three-Channel Context**: System instructions (15%) + Working memory (50%) + Conversation history (35%)
+  - **Agent context configuration**: `context { compression "graduated" cache-aware true working-memory true working-memory-tokens 5000 }`
+- **TranscriptStore SSOT (v1.16)**: Single Source of Truth for all conversation messages
+  - **Persistent Sessions**: All conversations auto-saved to `~/.helen/sessions/<session_id>/`
+  - **Dual Backends**: JSONL (simple, human-readable) or SQLite (WAL mode, indexed, fast)
+  - **LRU Cache**: Memory-efficient (configurable `max_memory_items`, default 1000)
+  - **UUID Addressing**: O(1) lookups via `get(uuid)`, no list index dependencies
+  - **Non-Destructive Compression**: BoundaryMarkers record compression events, full audit trail
+  - **View Caching**: Dirty flag + cached view for O(1) reads
+  - **REPL Commands**: `:transcript [--full|--audit]`, `:sessions`, `:session_id`
+  - **Stdlib Functions**: `get_session_id()`, `list_sessions()`, `replay_transcript()`, `export_transcript()`, `get_compression_audit()`, `get_session_dir()`, `set_session_dir()`
+  - **Session Scope (v1.20)**: transcripts 默认按作用域存储——项目目录 `.helen/sessions/`（检测到 `.helen/`、`helen.yaml`、`helen.toml` 时）或全局 `~/.helen/sessions/`（REPL、脚本）。通过 `session_scope: "auto"|"global"|"project"` 配置，或 `HELEN_SESSION_DIR` 环境变量强制指定路径
+  - **Configuration**:
+    ```yaml
+    transcript:
+      enabled: true              # Default: true (SSOT enabled)
+      backend: "sqlite"          # or "jsonl"
+      session_scope: "auto"      # "auto" (default) | "global" | "project"
+      session_dir: "~/.helen/sessions"          # used when scope=global
+      project_session_dir: ".helen/sessions"    # used when scope=project
+      max_memory_items: 1000     # LRU cache size
+    ```
+
+## Configuration
+
+Helen uses `~/.helen/config.yaml`:
+```yaml
+llm:
+  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+  api_key: "your-key"
+  model: "qwen3.7-plus"
+
+transcript:
+  enabled: true
+  backend: "sqlite"
+  session_scope: "auto"                  # v1.20: "auto" (default) | "global" | "project"
+  session_dir: "~/.helen/sessions"       # scope=global 时使用
+  project_session_dir: ".helen/sessions" # scope=project 时使用
+  max_memory_items: 1000
+
+multimodal:                          # v1.17
+  max_media_size_mb: 20              # 单个媒体最大 20MB
+  max_media_per_request: 10          # 每次最多 10 个媒体
+  video_frame_interval: 1.0          # 默认视频抽帧间隔（秒）
+  media_cache_dir: "~/.helen/media_cache"
+```
+Also supports `.env` format and falls back to `~/.hermes/.env`.
+
+## Testing Architecture
+
+Tests in `tests/` mirror the source structure:
+- `core/` — Lexer, parser, AST, tokens, errors
+- `semantic/` — Semantic analyzer, agent scope isolation
+- `interpreter/` — Interpreter, isolation (v1.12)
+- `execution/` — End-to-end (agents, control flow, functions, imports, match, exceptions, v1.12 isolation, v1.18 spawn)
+- `runtime/` — LLM runtime, tools, memory, history, config, imports, working memory, graduated compression, cache-aware compression, transcript store, session manager
+- `stdlib/` — Standard library functions, context management, transcript functions
+- `language/` — Feature tests (v16-v18: pattern matching, closures, protocols)
+- `performance/` — Benchmarks
+- `integration/` — Full agent integration
+- `lsp/` — Language Server
+- `cli/` — CLI and REPL
+
+**2791+ tests passing** (Python pytest)
+
+Helen also has a built-in test framework (`helen/stdlib/test.py`) with `test()`, `assert_equal()`, `assert_true()`, `assert_throws()`, expect chains, suites, filtering, JSON output, watch mode, and coverage tracking.
+
+## Skill System (Two-Tier Disclosure)
+
+Helen has its own skill system (similar to Claude Code skills):
+- **Tier 1**: Lightweight skill index injected into system prompt (name + description + tags)
+- **Tier 2**: Full SKILL.md content loaded on-demand via `load_skill` tool
+- Skill locations (priority order):
+  1. `<project>/.helen/skills/` (project-level)
+  2. `~/.helen/skills/` (user-level)
+  3. `<helen-install>/skills/` (built-in — 16 skills)
+  4. `~/.hermes/skills/` (Hermes fallback)
+- Each skill is a directory with `SKILL.md` (YAML frontmatter + markdown content)
+- Skills can have `references/` subdirectory for supplementary documents
+
+## Claude Code Skill Conversion Assessment
+
+Helen's 16 built-in skills can be categorized for Claude Code conversion:
+
+### Helen-Specific Skills (convert for Helen development assistance)
+| Skill | Lines | Purpose |
+|-------|-------|---------|
+| helen-syntax | 967 | Complete language syntax reference (92 keywords, types, expressions) |
+| helen-stdlib | 533 | 198 built-in functions reference with examples |
+| helen-testing | 589 | Test framework usage, TDD workflow, agent testing |
+| helen-quality | 107 | 7-dimension quality assessment guide |
+| helen-agent-patterns | 1115 | Agent design patterns (7 patterns + history management) |
+| helen-agent-collaboration | 773 | Multi-agent collaboration patterns (6 patterns) |
+| helen-language-development | 472 | Language implementation patterns (AST, parser, interpreter extension) |
+| helen-programming-methodology | 437 | Contract-first + TDD + quality workflow |
+| hellen-consistency-checker | 1040 | Design document consistency checking |
+
+### Generic Skills (already applicable to any project)
+| Skill | Lines | Purpose |
+|-------|-------|---------|
+| code-quality | 403 | 7-dimension scoring, pre-commit verification, parallel cleanup |
+| debugging | 302 | Systematic debugging methodology + language-specific tools |
+| plan | 339 | Plan mode: write actionable plans without execution |
+| test-driven-development | 355 | Strict TDD enforcement (RED-GREEN-REFACTOR) |
+| subagent-driven-development | 625 | Execute plans via subagents with 2-stage review |
+| writing-plans | 300 | Implementation plan writing craft |
+| github | 324 | Complete GitHub workflow (PRs, issues, CI/CD) |
+
+### Conversion Strategy
+1. **Direct mapping**: Helen's SKILL.md format is already compatible with Claude Code skill format (both use YAML frontmatter + markdown)
+2. **Helen-specific skills** → Create as project skills in `.claude/skills/helen-*` for Helen development
+3. **Generic skills** → Already exist in Claude Code ecosystem; no conversion needed
+4. **Priority**: helen-syntax, helen-stdlib, helen-testing (most frequently needed for Helen dev)

helen_lang-1.20.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Helen 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.

helen_lang-1.20.0/MANIFEST.in

@@ -0,0 +1,28 @@
+# MANIFEST.in — include non-Python resources in source distribution
+
+include LICENSE
+include README.md
+include CLAUDE.md
+
+# Skills (built-in skill definitions distributed with the language)
+recursive-include helen/skills *.md
+
+# Agent program (Helen self-assistant)
+recursive-include helen/agent *.helen
+
+# PEP 561 marker
+include helen/py.typed
+
+# Exclude build/test artifacts
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude *.so
+prune .git
+prune .github
+prune tests
+prune docs
+prune examples
+prune reports
+prune wiki
+prune vscode-extension
+prune extensions

helen_lang-1.20.0/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: helen-lang
+Version: 1.20.0
+Summary: Helen — A Prompt-first Agent Programming Language for AI-native applications
+Author-email: Helen Team <2229855189@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahalee000000/helen
+Project-URL: Repository, https://github.com/hahalee000000/helen
+Project-URL: Issues, https://github.com/hahalee000000/helen/issues
+Keywords: helen,dsl,agent,llm,ai,prompt,language
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Provides-Extra: accurate-tokens
+Requires-Dist: tiktoken>=0.5.0; extra == "accurate-tokens"
+Provides-Extra: all
+Requires-Dist: tiktoken>=0.5.0; extra == "all"
+Dynamic: license-file
+
+# Helen — 为 AI Agent 设计的提示词优先编程语言
+
+[![PyPI version](https://img.shields.io/pypi/v/helen-lang.svg)](https://pypi.org/project/helen-lang/)
+[![Python](https://img.shields.io/pypi/pyversions/helen-lang.svg)](https://pypi.org/project/helen-lang/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-2917%20passed-green.svg)](https://github.com/hahalee000000/helen)
+
+**Helen** 是一门专为 AI Agent 开发设计的 AI 原生 DSL（领域特定语言）。它将确定性构造（变量、函数、控制流）与一等 LLM 原语（`llm act`、`llm if`）融合为一门语言。
+
+## ✨ 为什么选择 Helen？
+
+- **Prompt-first**：`agent` 是一等公民，Agent 即语言构造而非库模式
+- **287 个内置 stdlib 函数**：287 个中英文双语函数覆盖 AI 应用开发全链路
+- **5 层渐进压缩 + 工作记忆**：长对话 Agent 自动管理上下文，无需手工调优
+- **Transcript SSOT**：会话记录以 SQLite/JSONL 持久化，支持审计与回放
+- **多 Agent 并发**：`spawn` + Channel 消息队列，内置 mailbox_select 多选
+- **Python 双向集成**：Helen → Python FFI + Python → Helen Bridge
+- **89 个双语关键字**：44.5 英文 + 44.5 中文，原生中文编程支持
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+pip install helen-lang
+```
+
+### Hello Helen
+
+创建 `hello.helen`：
+
+```helen
+agent Greeter(name: str) {
+    description "A friendly greeter"
+    prompt "Greet {{name}} warmly in one sentence"
+    
+    main {
+        return llm act "Greet {{name}} warmly"
+    }
+}
+
+main {
+    let g = Greeter("World")
+    print(g)
+}
+```
+
+运行：
+
+```bash
+helen hello.helen
+# Hello, World! It's wonderful to meet you!
+```
+
+### REPL 交互
+
+```bash
+helen repl
+> let x = 1 + 2
+> print(x)
+3
+> :help
+```
+
+### Python Bridge 用法
+
+Helen Agent 可以通过 Python Bridge 直接在 Python 中使用，就像使用普通的 Python 类：
+
+1. 创建 Helen Agent 文件 `translator.helen`：
+
+```helen
+agent TranslatorAgent(text: str, target: str) {
+    description "翻译文本到目标语言"
+    prompt "Translate '{{text}}' to {{target}}"
+    
+    main {
+        return llm act "Translate '{{text}}' to {{target}}"
+    }
+}
+```
+
+2. 在 Python 中导入并调用：
+
+```python
+from translator import TranslatorAgent
+
+agent = TranslatorAgent()
+result = agent("Hello", "French")
+print(result)  # "Bonjour"
+```
+
+### Python 集成特性
+
+- **直接导入 .helen 文件**：`from my_agents import TranslatorAgent`
+- **类型提示支持**：IDE 自动补全 Helen Agent
+- **异步调用**：`await agent.async_call(...)`
+- **装饰器模式**：`@helen_agent` 装饰 Python 函数
+- **参数验证**：Helen 自动校验 Agent 参数类型
+
+```python
+from helen.python_bridge import helen_agent
+
+@helen_agent("translator.helen", "TranslatorAgent")
+def translate(text: str, target: str) -> str:
+    pass
+
+result = translate("Hello", "French")
+```
+
+## 🎯 使用场景
+
+### AI Agent 开发
+
+```python
+from agents import ResearchAgent, AnalysisAgent
+
+# 研究阶段
+researcher = ResearchAgent()
+findings = researcher("quantum computing", depth="deep")
+
+# 分析阶段
+analyzer = AnalysisAgent()
+insights = analyzer(findings)
+```
+
+### 多 Agent 协作
+
+```python
+from workflow import PlannerAgent, ExecutorAgent, ReviewerAgent
+
+planner = PlannerAgent()
+plan = planner("Build a web app")
+
+executor = ExecutorAgent()
+result = executor(plan)
+
+reviewer = ReviewerAgent()
+feedback = reviewer(result)
+```
+
+### LLM 应用
+
+```python
+from llm_agents import ChatBot, Summarizer, Translator
+
+chatbot = ChatBot()
+response = chatbot("What is AI?")
+
+summarizer = Summarizer()
+summary = summarizer(long_text)
+
+translator = Translator()
+translated = translator(summary, target="Chinese")
+```
+
+## 🛠️ API 参考
+
+### HelenAgentWrapper
+
+```python
+class HelenAgentWrapper:
+    def __init__(self, agent_name: str, helen_file: str, interpreter=None)
+    
+    def __call__(self, *args, **kwargs) -> Any
+        """调用 agent"""
+    
+    async def async_call(self, *args, **kwargs) -> Any
+        """异步调用 agent"""
+```
+
+### 装饰器
+
+```python
+@helen_agent(helen_file: str, agent_name: str = None)
+def my_function(...):
+    """将函数包装为 Helen agent 调用"""
+
+@helen_module(helen_file: str)
+class MyModule:
+    """将类包装为 Helen agents 集合"""
+```
+
+### Import Hook
+
+```python
+from helen.python_bridge import install_import_hook
+
+# 自动安装（默认）
+install_import_hook()
+
+# 手动卸载
+from helen.python_bridge import uninstall_import_hook
+uninstall_import_hook()
+```
+
+## 📖 更多示例
+
+### 批量处理
+
+```python
+from agents import TranslatorAgent
+
+agent = TranslatorAgent()
+texts = ["Hello", "World", "AI"]
+
+results = [agent(text, target="French") for text in texts]
+print(results)  # ["Bonjour", "Monde", "IA"]
+```
+
+### 错误处理
+
+```python
+from agents import TranslatorAgent
+
+agent = TranslatorAgent()
+
+try:
+    result = agent("Hello", target="French")
+except TypeError as e:
+    print(f"参数错误: {e}")
+except Exception as e:
+    print(f"执行错误: {e}")
+```
+
+### 共享解释器
+
+```python
+from helen.interpreter import Interpreter
+from helen.python_bridge import HelenAgentWrapper
+
+# 创建共享解释器
+interpreter = Interpreter()
+
+# 多个 agent 共享同一个解释器
+agent1 = HelenAgentWrapper("Agent1", "agents.helen", interpreter)
+agent2 = HelenAgentWrapper("Agent2", "agents.helen", interpreter)
+```
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。
+
+## 📄 许可证
+
+MIT License
+
+## 🔗 链接
+
+- 文档：https://helen.readthedocs.io
+- GitHub：https://github.com/hahalee000000/helen
+- PyPI：https://pypi.org/project/helen-lang
+
+## 📚 文档
+
+- [Wiki 文档](wiki/index.md) - 完整的技术文档
+- [教程](docs/tutorial.md) - 从零开始学习 Helen
+- [Python Bridge 教程](wiki/tutorial/15-python-bridge.md) - Python 集成指南
+- [上下文管理](wiki/runtime/context-management.md) - 智能上下文处理（v1.20）
+- [技能系统](wiki/runtime/skills.md) - 技能加载和使用
+
+## 🆕 版本历史
+
+### v1.20 - Transcript 会话作用域
+- Transcripts 默认按应用隔离在 `.helen/sessions/`（REPL 场景 opt-in 全局）
+- `session_scope` 配置：`auto` | `global` | `project`
+- `HELEN_SESSION_DIR` 环境变量强制指定路径
+- 新增 `get_session_dir()` / `set_session_dir()` stdlib 函数
+
+### v1.19 - 上下文管理 API 完善
+- 补齐 6 维度 API（Inspection/Working Memory/Fine-grained Mutation/Runtime Config/Query/Multi-agent Transfer）
+- 新增 24 个 stdlib 函数：`context_stats`/`context_usage`/`pin_message`/`working_memory_*`/`export_context` 等
+- `Message.pinned: bool` 字段，pinned 消息免疫全部 5 层压缩
+- 内部化 `classify_message`
+
+### v1.18 - spawn 并发原语
+- `spawn Agent(...)` 返回 Channel，替代 `async/await/detach`
+- Channel 消息队列：`send/receive/try_receive/cancel/close`
+- `mailbox_select()` 多选原语
+- 流式中断：`on_chunk` 回调返回 `false` 停止流式；Ctrl+C 中断
+
+### v1.16 - TranscriptStore SSOT
+- 对话历史 SSOT，SQLite/JSONL 双后端
+- LRU 缓存（10K messages ~10MB）
+- UUID 寻址，O(1) 查找
+- 非破坏性压缩（BoundaryMarker 审计）
+
+### v1.15 - 上下文管理增强
+- Working Memory（工作记忆）
+- Graduated Compression（渐进式压缩）
+- Cache-Aware Compression（缓存感知压缩）
+- Three-Channel Context（三通道上下文）
+- Agent context configuration
+
+
+### v1.14 - LLM 流式支持
+- `llm act` 支持流式输出（on_chunk/on_complete 回调）
+- `llm stream` 已删除（功能合并到 `llm act`）
+
+### v1.13 - Python Bridge
+- Python 直接导入和使用 Helen Agent
+- 双向 FFI（Helen ↔ Python）
+
+### v1.12 - Agent 隔离增强
+- Agent 隔离级别（@open, @strict, @sandbox）
+- Shared store 和 channel
+- ReadOnlyView
+- 闭包值捕获
+
+### v1.10 - 核心特性
+- Agent 作用域隔离
+- 短路求值
+- 下标/字段赋值
+- 别名语句