opentulpa-engineering

分类: 开发与编程 | 上传者: kvyb | 下载: 0 | 版本: v1.0（最新）

为 OpenTulpa 代码库实施可维护、可测试且稳健的工程实践。在此存储库中实现功能、重构、错误修复或集成时使用，特别是对于 LangGraph 运行时、FastAPI 路由、Telegram 接口、调度程序/任务流和内存/指令行为。应用此技能来计划关注点分离更改、保留运行时行为以及运行特定于存储库的质量门和回归检查。

更新日志: Source: GitHub https://github.com/kvyb/opentulpa

目录结构

当前层级: tree/main/skills/opentulpa-engineering/

📁 agents/
- 📄 openai.yaml 215 B
📁 references/
- 📄 external-sources.md 585 B
- 📄 quality-gate.md 819 B
- 📄 test-matrix.md 1.3 KB
📁 scripts/
- 📄 quality_gate.py 3.5 KB
📄 SKILL.md 3.3 KB

SKILL.md

---
name: opentulpa-engineering
description: Enforce maintainable, testable, and robust engineering practices for the OpenTulpa codebase. Use when implementing features, refactors, bug fixes, or integrations in this repository, especially for LangGraph runtime, FastAPI routes, Telegram interfaces, scheduler/task flows, and memory/directive behavior. Apply this skill to plan separation-of-concerns changes, preserve runtime behavior, and run repository-specific quality gates and regression checks.
---

# OpenTulpa Engineering

## Overview

Implement OpenTulpa changes with small modules, explicit boundaries, and repeatable verification.
Prefer behavior-preserving refactors backed by targeted tests and deterministic smoke checks.

## Workflow

1. Scope impact before editing.
2. Keep modules focused and dependency-injected.
3. Add or update tests for changed behavior.
4. Run quality gates and smoke checks before finishing.
5. Report what is proven vs what remains unproven.

## Scope First

- Read the touched component and its immediate callers before edits.
- Map change boundaries to current structure:
  - `src/opentulpa/agent/*` for runtime, graph, tools, compaction, file analysis.
  - `src/opentulpa/interfaces/telegram/*` for interface concerns (client, formatting, relay, chat orchestration).
  - `src/opentulpa/api/app.py` (or future route modules) for HTTP wiring.
  - `src/opentulpa/tasks/*` and `src/opentulpa/scheduler/*` for background execution.
- Avoid broad rewrites when only one concern changes.

## Design Rules

- Keep orchestration thin; move logic into focused modules.
- Isolate pure logic in helpers so unit tests do not require network or process startup.
- Inject services/clients (`memory`, `file_vault`, runtime deps) instead of hard-coding globals where feasible.
- Preserve external contracts unless the task explicitly changes them:
  - route paths and payload shapes,
  - tool names and required args,
  - wake/notification semantics,
  - directive/time-profile behavior.
- Remove dead compatibility code when migration is intentional and approved.

## Testing Rules

- Add tests in `tests/` for every behavior change or bug fix.
- Prefer layered coverage:
  - Unit tests for pure helpers.
  - Integration tests for FastAPI handlers with `TestClient`.
  - Runtime/graph tests with deterministic fakes/mocks.
- Mock external boundaries:
  - OpenRouter/model calls,
  - network fetches (`httpx`),
  - Telegram/Slack API calls,
  - filesystem side effects when not under test.
- Assert observable behavior, not private implementation details.

## Mandatory Verification

Run this from repository root after edits:

```bash
UV_CACHE_DIR=.opentulpa/.uv-cache \
  uv run python skills/opentulpa-engineering/scripts/quality_gate.py --smoke
```

Use `--strict-tests` when you expect real pytest coverage and want failure on "no tests collected".

## Refactor Acceptance Criteria

- Lint passes.
- Code compiles.
- Existing tests pass.
- New/updated tests validate changed behavior.
- Smoke checks pass for runtime/API/Telegram entry points.
- Summary clearly states parity confidence and any remaining risk.

## References

- Use `references/quality-gate.md` for command policy and pass/fail interpretation.
- Use `references/test-matrix.md` for what to test per subsystem.
- Use `references/external-sources.md` for authoritative upstream docs used by this skill.

登录后下载/点赞/收藏 ❤ 27 | ★ 0

opentulpa-engineering

目录结构

SKILL.md

举报内容

提示