feat: add dev and AI setup scripts#856
Merged
shentongmartin merged 13 commits intomainfrom Mar 12, 2026
Merged
Conversation
Adds scripts/dev_setup.sh which clones eino-ext and eino-examples into local subdirectories (ext/, examples/) and creates a go.work covering all 83 modules across the three repos. Everything is excluded via .git/info/exclude and .gitignore — no remote changes required. Change-Id: I4d7432d4d4471c39dfe1230369c9fbf09649354d Usage: bash scripts/dev_setup.sh [--reset]
Change-Id: I5dde2c0aa913e0ea175ff5ece45b5ca9e7c8768d
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #856 +/- ##
==========================================
+ Coverage 81.56% 81.60% +0.04%
==========================================
Files 146 146
Lines 15932 15937 +5
==========================================
+ Hits 12995 13006 +11
+ Misses 1995 1989 -6
Partials 942 942 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
shentongmartin
changed the title
Change-Id: I209c390fda47b46a7a2b0672092a79bf969b4bfe
- embedding: package overview, vector dimension consistency warning, implementor option helpers - retriever: RAG context, score threshold vs sort distinction, embedding consistency requirement, DSLInfo clarification - indexer: vector dimension matching requirement, Store/SubIndexes guidance - document: Loader vs Parser separation, metadata preservation guidance - document/parser: new doc.go, reader-consumed contract, ExtParser usage, ExtraMeta propagation - prompt: template syntax options, MessagesPlaceholder, variable mismatch runtime error warning - tool: interface hierarchy, standard vs enhanced distinction, interface priority rule, interrupt/resume overview - tool/utils: struct tag convention (separate jsonschema_description), Infer vs New constructor choice, GoStruct2* for structured output - components/types: Typer naming convention, Checker callback control semantics Change-Id: Ic5b7b35b728efc8a2ab313411bcb137caeb86d34
- schema/doc.go: full package overview covering Message, Document, ToolInfo, StreamReader with key constraints and utility function cross-references - schema/stream.go: StreamReader (read-once contract, close requirement, Copy for fan-out), MergeStreamReaders, MergeNamedStreamReaders (SourceEOF per-source signalling), StreamReaderWithConvert (ErrNoValue filtering), ErrNoValue sentinel - schema/document.go: Document metadata philosophy (open map + typed accessors), WithScore/WithSubIndexes/WithDSLInfo clarifications - schema/tool.go: ToolInfo, ParamsOneOf two-approach docs with trade-off guidance, ToolChoice values with OpenAI mapping - callbacks/doc.go: rewritten with 5-timing overview, global vs per-run attachment, both builder approaches, common pitfalls (stream leak, AppendGlobalHandlers thread safety, stream errors invisible to OnError) - callbacks/interface.go: RunInfo fields + nil pitfall, CallbackInput ConvCallbackInput pattern, Handler stream-copy contract, AppendGlobalHandlers init-only warning, timing constants with streaming-specific notes, TimingChecker overhead rationale - callbacks/aspect_inject.go: OnStart/OnEnd/OnError/OnStartWithStreamInput/ OnEndWithStreamOutput with stream-copy + close requirement, EnsureRunInfo usage guidance - callbacks/handler_builder.go: HandlerBuilder full example with typed extraction, OnStartWithStreamInputFn/OnEndWithStreamOutputFn close mandate Change-Id: Idedbaf92c81f9c1886f2dec5363d2a93ef31a8c6
After reading the actual cloudwego.io documentation: schema/doc.go: - Add four streaming paradigms section (Invoke/Stream/Collect/Transform) - Explain fake stream (T boxed into single-chunk StreamReader) and auto-concat (StreamReader collapsed to T) — the framework bridges mismatches - Correct the doc URL to the stream programming essentials page callbacks/doc.go: - Add handler inheritance (child ctx inherits parent handlers) - Add DesignateNode targeted handler injection - Add "Passing State Within a Handler" section with ctx.WithValue example - Clarify: context flows between timings of the SAME handler, not between different handlers (no guaranteed order) - Expand stream copy pitfall: N handlers means N+1 copies; any unclosed copy blocks the entire pipeline - Add "do NOT mutate Input/Output" pitfall (shared pointer, data race risk) - Add RunInfo nil-check pitfall for standalone usage callbacks/interface.go: - RunInfo: clarify Name is empty when not set, standalone requires manual setup; Type falls back to reflection; no guaranteed order between handlers - Handler: add context-flows-within-same-handler rule, explicit no-order guarantee between handlers, and no-mutation rule callbacks/aspect_inject.go: - Fix bug in old example block: was calling OnEnd(ctx, err) on error path, should be OnError(ctx, err) - Add ReuseHandlers doc with nested component usage example - Add InitCallbacks doc with standalone usage example Change-Id: I0b83c93c48fe19ffebb616db06156f9d3257f795
Change-Id: I252e6945aaa682ddaa2d6c22ade0a89be972dcef
…dictions Change-Id: I83eb8b0dcd8f3404da16675a4f143132c270bc85
Change-Id: I57c42c14691a73de7b8910ee2c1c15142c266bf2
Change-Id: I1cc8305088d4da478c2eb52e0b964be050b1a857
Clones eino, eino-ext, and eino-examples into _eino/ inside the user's project so AI coding assistants have full framework source context. Includes sample system prompt for CLAUDE.md / .cursorrules. Change-Id: I8c975b08d712514fb0aeb70583a2941237f2628e
Change-Id: I7888faf4cafe40256f86ebc226129a11cbe2dc18
Change-Id: I4aac934a537329819bf945d5d4bdc97ea882f924
shentongmartin
force-pushed
the
feat/dev-setup-script
branch
from
55a1ce2 to
8128682
Compare
hi-pender
reviewed
Mar 11, 2026
hi-pender
approved these changes
Mar 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds setup tooling to make cross-repo development and AI-assisted usage of Eino easier:
scripts/dev_setup.sh: cloneseino-extandeino-examplesunder this repo and generates a gitignoredgo.workfor full cross-module LSP (go-to-definition, type info, autocomplete).scripts/eino_setup.sh: for downstream projects, cloneseino+eino-ext+eino-examplesinto a gitignored_eino/reference directory so AI assistants can browse framework source and examples.Also:
llms.txtfor AI tooling discoverability.components/,schema/, andcallbacks/to align with the official docs and improve in-editor guidance..gitignoreto avoid accidentally committing local/AI setup artifacts.Motivation
Working across
eino/eino-ext/eino-examplescurrently requires manual cloning and editor setup. Editors and AI tools often lack cross-module navigation, which slows iteration and can lead to incorrect wiring.Design Notes
dev_setup.shuses.git/info/excludesoext/andexamples/stay local-only without changing the public repo’s tracked files.eino_setup.shuses_eino/(gitignored) so downstream repos keep normalgo.moddependencies while still giving assistants full source context.doc.gofiles to satisfy linting rules.Testing
golangci-lint run --new-from-rev=main ./...go test -race ./...go test -coverprofile=coverage.out ./...概要
新增一套用于提升跨仓库开发体验和 AI 辅助使用体验的脚本与文档：
scripts/dev_setup.sh：在本仓库下克隆eino-ext与eino-examples，并生成（已在 gitignore 中）go.work，让编辑器获得完整的跨模块 LSP 能力（跳转定义、类型信息、补全等）。scripts/eino_setup.sh：面向下游业务仓库，将eino+eino-ext+eino-examples克隆到（已在 gitignore 中）_eino/目录，方便 AI 助手直接阅读框架源码与示例。另外：
llms.txt，提升 AI 工具对仓库的可发现性。components/、schema/、callbacks/的 GoDoc，使其与官方文档一致，并提升编辑器内的使用指引。.gitignore，避免本地/AI 环境相关文件被误提交。背景与动机
当前在
eino/eino-ext/eino-examples之间联调通常需要手动克隆与配置；编辑器和 AI 工具也经常缺少跨模块导航，导致迭代变慢、接线方式更容易出错。设计说明
dev_setup.sh使用.git/info/exclude，让ext/与examples/保持本地私有，不改变公开仓库中被跟踪的文件。eino_setup.sh使用_eino/（gitignored），让下游仓库保持正常的go.mod依赖方式，同时为 AI 助手提供完整源码上下文。doc.go，以满足 lint 规则要求。测试
golangci-lint run --new-from-rev=main ./...go test -race ./...go test -coverprofile=coverage.out ./...Closes #616