feat: add library service injection and SDK docs

Author: fengjiayi

.gitignore

@@ -42,3 +42,7 @@ frontend/sereinflow-web/coverage/
 frontend/sereinflow-web/output-vite.err
 /.artifacts
 /NuGet/Migrations
+/.dotnet-cli/.dotnet
+/.build-temp
+/.dotnet-session
+/.compile-check

Directory.Packages.props

@@ -7,6 +7,7 @@
   <ItemGroup>
     <PackageVersion Include="coverlet.collector" Version="6.0.4" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.11" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.11" />
     <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.11" />
     <PackageVersion Include="SqlSugarCore" Version="5.1.4.217" />

src/SereinFlow.Api/mcp/sereinflow-library-package-skill.md

@@ -22,16 +22,28 @@ output and its dependency closure first.
 
 Use an SDK-style C# class library targeting a runtime supported by the
 deployment. The current repository examples target `net10.0`.
-`SereinFlow.Library` version `1.0.0` is published on
+`SereinFlow.Library` is published on
 [NuGet.org](https://www.nuget.org/packages/SereinFlow.Library/). Reference it
-as the standalone public SDK package:
+as the standalone public SDK package with NuGet's floating version to use the
+latest stable release by default:
 
 ```xml
 <ItemGroup>
-  <PackageReference Include="SereinFlow.Library" Version="1.0.0" />
+  <PackageReference Include="SereinFlow.Library" Version="*" />
 </ItemGroup>
 ```
 
+When the caller needs a specific compatible version for reproducible builds or
+deployment compatibility, they may replace `*` with the requested version:
+
+```xml
+<PackageReference Include="SereinFlow.Library" Version="x.y.z" />
+```
+
+For a project that uses Central Package Management, keep the project reference
+without a `Version` attribute and set either `*` or the caller's requested
+version in `Directory.Packages.props`.
+
 The package supplies the public metadata attributes and restricted runtime
 context without referencing SereinFlow Domain, Application, or server
 implementation assemblies. Restore it from NuGet.org using the normal NuGet
@@ -42,9 +54,9 @@ Never replace the `PackageReference` with a DLL reference and never copy local
 definitions of the SDK contracts into the library. Do not add a custom SDK
 package source merely to obtain `SereinFlow.Library`. If the caller
 explicitly works offline or behind an approved package mirror, use their
-provided source only when it contains the published package version; report a
-missing source or unavailable package without silently modifying the user's
-global NuGet configuration.
+provided source only when it contains a suitable published package version;
+report a missing source or unavailable package without silently modifying the
+user's global NuGet configuration.
 
 Let MSBuild evaluate these properties; do not parse inherited build files by
 hand:

src/SereinFlow.Contracts/LibraryAttributes.cs

@@ -8,4 +8,7 @@
 [assembly: TypeForwardedTo(typeof(FlowNodeAttribute))]
 [assembly: TypeForwardedTo(typeof(NodeParamAttribute))]
 [assembly: TypeForwardedTo(typeof(NodeType))]
+[assembly: TypeForwardedTo(typeof(FlowServiceLifetime))]
+[assembly: TypeForwardedTo(typeof(FlowServiceAttribute))]
+[assembly: TypeForwardedTo(typeof(FlowServiceAttribute<>))]
 [assembly: TypeForwardedTo(typeof(LibraryAttributeContract))]

src/SereinFlow.Library/FlowContext.cs

@@ -1,32 +1,76 @@
 namespace SereinFlow.Runtime.Abstractions;
 
 /// <summary>
-/// Restricted per-node context exposed to trusted node-library methods.
-/// It allows a node to select an execution branch without exposing arbitrary
-/// flow data, environment variables, or host services.
-/// 提供给受信任节点类库方法的受限上下文。节点可以选择执行分支，但不能访问任意流程数据、
+/// Provides restricted per-node context to trusted node-library methods. It allows a node to
+/// select an execution branch without exposing arbitrary flow data, environment variables, or
+/// host services.
+/// 向受信任的节点类库方法提供受限的节点上下文。它允许节点选择执行分支，但不会公开任意流程数据、
 /// 环境变量或宿主服务。
 /// </summary>
 public interface IFlowContext
 {
+    /// <summary>
+    /// Gets the unique identifier of the active flow run.
+    /// 获取当前活动流程运行的唯一标识。
+    /// </summary>
     Guid RunId { get; }
 
+    /// <summary>
+    /// Gets the stable identifier of the node currently being invoked.
+    /// 获取当前正在调用节点的稳定标识。
+    /// </summary>
     string NodeId { get; }
 
+    /// <summary>
+    /// Gets the token that is cancelled when the Worker stops or cancels the current flow run.
+    /// 获取当 Worker 停止或取消当前流程运行时会被取消的令牌。
+    /// </summary>
     CancellationToken CancellationToken { get; }
 
+    /// <summary>
+    /// Selects the success branch for the current node invocation.
+    /// 为当前节点调用选择成功分支。
+    /// </summary>
     void SelectSuccess();
 
+    /// <summary>
+    /// Selects the failure branch for the current node invocation.
+    /// 为当前节点调用选择失败分支。
+    /// </summary>
+    /// <param name="code">
+    /// An optional machine-readable failure code.
+    /// 可选的、可供机器读取的失败代码。
+    /// </param>
+    /// <param name="message">
+    /// An optional human-readable failure message.
+    /// 可选的、供人阅读的失败消息。
+    /// </param>
     void SelectFailure(string? code = null, string? message = null);
 
+    /// <summary>
+    /// Selects the error branch for the current node invocation.
+    /// 为当前节点调用选择错误分支。
+    /// </summary>
+    /// <param name="code">
+    /// An optional machine-readable error code.
+    /// 可选的、可供机器读取的错误代码。
+    /// </param>
+    /// <param name="message">
+    /// An optional human-readable error message.
+    /// 可选的、供人阅读的错误消息。
+    /// </param>
     void SelectError(string? code = null, string? message = null);
 }
 
 /// <summary>
-/// Metadata identity used by the safe PE scanner.
-/// 供安全 PE 扫描使用的元数据身份。
+/// Provides the metadata identity used by the safe PE scanner.
+/// 提供安全 PE 扫描器使用的元数据标识。
 /// </summary>
 public static class FlowContextContract
 {
+    /// <summary>
+    /// Gets the fully qualified metadata name of <see cref="IFlowContext"/>.
+    /// 获取 <see cref="IFlowContext"/> 的完全限定元数据名称。
+    /// </summary>
     public static readonly string FullName = typeof(IFlowContext).FullName ?? nameof(IFlowContext);
 }